WMS_MAIN/docs/api-doc-update-workflow.md
2026-04-27 16:09:26 +08:00

4.0 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

注意:所有对 methods/*.json 与 methods/changes/*.json 的变更必须通过 spec + 脚本完成。spec 是唯一输入来源,不接受直接手写或直接提交目标 JSON 的改动。

固定命令

务必按顺序执行:复制 example -> 编辑 spec -> dry-run -> 修正 -> 正式写入。示例命令(PowerShell):

先做 dry-run(验证和查看差异):

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

确认 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 是否可解析
  • 在 dry-run 模式下不写入,仅打印将要变更的差异并返回校验结果
  • 按 group + method 做 upsert,避免覆盖或破坏其他分组/方法
  • 检查 change version 是否重复并拒绝冲突写入
  • 尽量保留目标 JSON 原有缩进与换行风格,减少无关 diff

脚本是对 methods JSON 的唯一写入通道;任何绕过脚本的改动都不被接受。

推荐流程

  1. 先核对代码与测试,确认真实接口契约
  2. 如果是 system 参数结构变化,可先执行 node .\script\tmp-struct-system-params.cjs
  3. 按 docs/api-doc-update-spec.example.json 复制一份 spec 到 temp/ 并在该文件上编辑
  4. 先执行 dry-run(--dry-run),阅读输出并修正 spec
  5. 确认无误后执行正式写入(不带 --dry-run)
  6. 最后补充必要的 docs/*.md 或 README.md

最小示例流程(PowerShell):

# 复制示例到 temp 并编辑
Copy-Item docs/api-doc-update-spec.example.json temp/api-doc-update.json

# 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