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

124 lines
4.0 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`
注意:所有对 `methods/*.json` 与 `methods/changes/*.json` 的变更必须通过 spec + 脚本完成。spec 是唯一输入来源,不接受直接手写或直接提交目标 JSON 的改动。
## 固定命令
务必按顺序执行:复制 example -> 编辑 spec -> dry-run -> 修正 -> 正式写入。示例命令(PowerShell):
先做 dry-run(验证和查看差异):
```powershell
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
```
确认 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` 是否可解析
- 在 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](docs/api-doc-update-spec.example.json) 复制一份 spec 到 `temp/` 并在该文件上编辑
4. 先执行 dry-run(`--dry-run`),阅读输出并修正 spec
5. 确认无误后执行正式写入(不带 `--dry-run`)
6. 最后补充必要的 `docs/*.md` 或 `README.md`
最小示例流程(PowerShell):
```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
```