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

2.9 KiB
Raw Blame History

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 结构固定如下:

{
  "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:

npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run

确认无误后执行写入:

npm run doc:api:update -- --spec=temp/api-doc-update.json

纯文档主文件修补且不追加 changes 时:

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 复制一份 spec 到 temp/
  4. 先执行 dry-run,再执行正式写入
  5. 最后补充必要的 docs/*.md 或 README.md