124 lines
4.0 KiB
Markdown
124 lines
4.0 KiB
Markdown
# 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
|
||
``` |