WMS_MAIN/docs/api-doc-update-workflow.md
2026-04-17 19:21:57 +08:00

103 lines
2.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# API 文档 JSON 固定写入流程
## 现有 JSON 结构
仓库内现有 API 文档分两类:
1. `methods/<docName>.json`
- 根节点是对象
- 关键字段固定为 `module`、`description`、`version`、`updatedAt`、`headers`、`methods.groups`
- `methods.groups` 为数组,每个 group 固定为 `groupName`、`module`、`list`
- `list` 中每个 method 固定包含 `method`、`description`、`isNeedAuth`、`isNeedLogin`、`headers`、`params`、`response`、`errors`
2. `methods/changes/<docName>.json`
- 根节点是数组
- 每条变更记录建议固定包含 `version`、`date`、`summary`、`methods`、`notes`
- 可选补充 `type`
## 固定输入 spec
后续 API 文档写入统一通过脚本读取一个 spec JSON 完成,spec 结构固定如下:
```json
{
"docName": "system",
"docMeta": {
"updatedAt": "2026-04-15",
"version": "0.3.5"
},
"group": {
"groupName": "基础模块",
"module": "index"
},
"methods": [
{
"method": "index.example",
"description": "接口说明",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [],
"params": [],
"response": [],
"errors": []
}
],
"change": {
"version": "2026.04.15-system-06",
"date": "2026-04-15",
"summary": "一句话说明本次接口文档变更",
"methods": [
"index.example"
],
"notes": [
"补充关键字段说明。"
],
"type": "updated"
}
}
```
说明:
- `docName` 目前必须对应已存在的 `methods/system.json`、`methods/qimen.json`、`methods/gateway.json`
- `group` 用于定位或创建目标分组
- `methods` 为要写入的完整 method 文档对象数组,脚本按 `method` 字段 upsert
- `change` 默认必填;仅当明确是纯格式修复且不需要追加历史时,才允许加 `--doc-only`
## 固定命令
先做 dry-run:
```powershell
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
```
确认无误后执行写入:
```powershell
npm run doc:api:update -- --spec=temp/api-doc-update.json
```
纯文档主文件修补且不追加 changes 时:
```powershell
npm run doc:api:update -- --spec=temp/api-doc-update.json --doc-only
```
## 脚本保证
`script/update-api-doc.cjs` 会执行以下动作:
- 校验 spec JSON 是否符合固定结构
- 校验目标 `methods/*.json` 与 `methods/changes/*.json` 是否可解析
- 按 group + method 做 upsert,避免手写 JSON 时把括号、逗号、层级写坏
- 检查 change version 是否重复
- 保留目标 JSON 原有缩进与换行风格
## 推荐流程
1. 先核对代码与测试,确认真实接口契约
2. 如果是 system 参数结构变化,可先执行 `node .\script\tmp-struct-system-params.cjs`
3. 按 [docs/api-doc-update-spec.example.json](docs/api-doc-update-spec.example.json) 复制一份 spec 到 `temp/`
4. 先执行 dry-run,再执行正式写入
5. 最后补充必要的 `docs/*.md` 或 `README.md`