4.0 KiB
4.0 KiB
API 文档 JSON 固定写入流程
现有 JSON 结构
仓库内现有 API 文档分两类:
-
methods/<docName>.json- 根节点是对象
- 关键字段固定为
module、description、version、updatedAt、headers、methods.groups methods.groups为数组,每个 group 固定为groupName、module、listlist中每个 method 固定包含method、description、isNeedAuth、isNeedLogin、headers、params、response、errors
-
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.jsongroup用于定位或创建目标分组methods为要写入的完整 method 文档对象数组,脚本按method字段 upsertchange默认必填;仅当明确是纯格式修复且不需要追加历史时,才允许加--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 的唯一写入通道;任何绕过脚本的改动都不被接受。
推荐流程
- 先核对代码与测试,确认真实接口契约
- 如果是 system 参数结构变化,可先执行
node .\script\tmp-struct-system-params.cjs - 按 docs/api-doc-update-spec.example.json 复制一份 spec 到
temp/并在该文件上编辑 - 先执行 dry-run(
--dry-run),阅读输出并修正 spec - 确认无误后执行正式写入(不带
--dry-run) - 最后补充必要的
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