# API 文档 JSON 固定写入流程 ## 现有 JSON 结构 仓库内现有 API 文档分两类: 1. `methods/.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/.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`