152 lines
6.1 KiB
Markdown
152 lines
6.1 KiB
Markdown
# API Doc System Workflow
|
||
|
||
该工作流用于抓取 `system` API 文档页面,按 `platform=网页端(web)`、`project=全部(all)` 条件进行校验后,清洗输出模块与接口数据。
|
||
|
||
## 目录结构
|
||
|
||
- `core/`: 核心实现目录(`config.mjs`、`update.mjs`、`clear-pending.mjs`)。
|
||
- `scripts/`: 脚本入口目录(`update.mjs`、`clear-pending.mjs`、`apidata.mjs`)。
|
||
- `system/`: 系统模式配置目录(如 `workflow-mode.json`)。
|
||
- `config.mjs`: 兼容转发入口(实际定义位于 `core/config.mjs`)。
|
||
- `scripts/agent/`: 从 `api-doc-agent` 迁移的 Agent 脚本(`run.mjs`、`api-list-update`、`interface-availability`)。
|
||
- `data/`: 数据目录,按功能分类存放产物。
|
||
- `data/module/<folder>/module.json`: 模块接口明细(覆盖更新)。
|
||
- `data/module-list/module-list.json`: 模块总览(覆盖更新)。
|
||
- `data/interface-details/interface-details.json`: 全量接口明细(覆盖更新)。
|
||
- `data/pending-updates.json`: 待更新文件(模块变化 + 接口变化)。
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
npm run apiconfig
|
||
```
|
||
|
||
如需清空待更新接口文件,可执行:
|
||
|
||
```bash
|
||
npm run apiconfig:clear-pending
|
||
```
|
||
|
||
执行前会先检查 `pending-updates.json`:
|
||
|
||
- 若文件内容不是 `{}`(存在未处理项),脚本会输出:
|
||
- `请先处理待更新接口再更新接口信息!`
|
||
- 并终止本次执行,不更新其他产物。
|
||
|
||
## Apidata 抓取脚本
|
||
|
||
新增 `apidata` 请求脚本,用于按配置发起接口请求并写入响应结果(支持提取登录 token)。
|
||
|
||
运行命令:
|
||
|
||
```bash
|
||
npm run apiconfig:apidata
|
||
```
|
||
|
||
配置文件:`workflows/api-doc-system/apidata/config.json`
|
||
|
||
- `config.json` 仅存放待请求接口配置(不存放爬虫地址、版本等信息)。
|
||
- `requests`: 请求列表
|
||
- `method`: 接口 method(会拼接到 `?method=xxx`)
|
||
- `body`: 请求 JSON(可省略,默认 `{}`)
|
||
- `needAuth`: 是否携带登录 token(可省略;除 `user.login` 外默认 `true`)
|
||
- 脚本内部固定请求地址:`http://192.168.11.56:6060/system?v=1.0`。
|
||
- 脚本默认携带请求头:`platform: web`、`project: all`。
|
||
|
||
示例配置(登录获取 token):
|
||
|
||
```json
|
||
{
|
||
"requests": [
|
||
{
|
||
"method": "user.login",
|
||
"body": {
|
||
"username": "yjm",
|
||
"password": "111111"
|
||
}
|
||
},
|
||
{
|
||
"method": "order.list",
|
||
"body": {}
|
||
},
|
||
{
|
||
"method": "order.manualOutboundOrder",
|
||
"body": {}
|
||
},
|
||
{
|
||
"method": "order.badgeCount",
|
||
"body": {}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
说明:
|
||
|
||
- 脚本会按 `requests` 顺序串行执行。
|
||
- 当某次响应中包含 `data.token`(如 `user.login`)时,后续 `needAuth=true` 的接口会自动携带 `Authorization: Bearer <token>`。
|
||
|
||
数据文件:`workflows/api-doc-system/apidata/data.json`
|
||
|
||
- 每次执行会先清空该文件,再写入本次抓取结果。
|
||
- 输出结构为数组项:`{ 接口, message, data }`。
|
||
- 同步更新:`workflows/api-doc-agent/config/响应.md`(写入本次结果)。
|
||
|
||
如需改抓取地址,可临时指定:
|
||
|
||
```bash
|
||
API_DOC_URL=http://192.168.11.56:6060/api/docs/system npm run apiconfig
|
||
```
|
||
|
||
Agent 脚本入口:
|
||
|
||
```bash
|
||
npm run apiagent -- --script list
|
||
```
|
||
|
||
## 输出说明(去历史回档)
|
||
|
||
- 模块文件包含当前模块全部接口信息(接口名、描述、Headers、Params、Response 等)。
|
||
- `module` 是最新接口信息的主数据源,每次执行 `npm run apiconfig` 都会覆盖更新 `module.json`。
|
||
- 每个模块快照新增 `changes.fromPreviousSnapshot` 字段,记录本模块相对上一快照的:
|
||
- 模块是否新增/重命名
|
||
- 接口新增/删除
|
||
- 接口 `params` 更新
|
||
- 接口 `response` 更新
|
||
- 模块总览文件仅保留每个模块的精简接口清单:
|
||
- `method`
|
||
- `module-list/module-list.json` 每次执行覆盖更新,避免每日堆积快照文件。
|
||
- `module-list` 与 `interface-details` 均新增 `changes` 字段,统一汇总模块与接口变化统计:
|
||
- `moduleUpdates.added / deleted / updated`
|
||
- `interfaceUpdates.added / deleted / paramsUpdated / responseUpdated`
|
||
- 接口明细文件包含当前项目所有接口信息,并带状态字段:
|
||
- `status.isUsed`: 是否使用(默认 `false`)
|
||
- `status.isPlaceholder`: 是否占位(默认 `false`)
|
||
- 状态会优先继承 `module` 目录最近快照中的状态,避免每次执行覆盖人工维护状态。
|
||
- 脚本输出增加本地可读时间字段(如 `generatedAtLocal`),终端日志统一显示 `YYYY-MM-DD HH:mm:ss`。
|
||
- 页面中的 `platform/project` 是全局请求头配置项,脚本会校验 `web/all` 选项存在,并将其写入每份产物的 `filter` 字段。
|
||
- `pending-updates.json` 中:
|
||
- 无任何变化时文件会被重置为 `{}`。
|
||
- 有变化时写入模块/接口变更清单,复杂迁移统一折叠为“新增 + 删除”。
|
||
- `summary`:包含 `moduleAdded`、`moduleDeleted`、`interfaceAdded`、`interfaceDeleted`、`interfaceParamsUpdated`、`interfaceResponseUpdated`、`totalChangedItems`
|
||
- `interfaceUpdates`:包含 `added`、`deleted`、`paramsUpdated`、`responseUpdated`
|
||
|
||
## 待更新接口判定规则
|
||
|
||
- 与上一轮有效快照对比后,以下变化会写入 `pending-updates.json`:
|
||
- 模块更新:新增模块、删除模块(拆分/合并/替换统一按增删处理)
|
||
- 接口更新:新增接口、删除接口、`params` 变化、`response` 变化
|
||
|
||
## 模块文件夹生命周期
|
||
|
||
- 新模块首次出现时自动创建模块文件夹并生成 `_module.lifecycle.json`。
|
||
- 运行 `npm run apiconfig` 时会先完成与上一轮数据的差异对比并写入 `pending-updates.json`。
|
||
- 对比完成后,当前文档中不存在的旧模块文件夹会被直接物理删除(不再保留 `_deleted.YYYYMMDD.json` 软删除标记)。
|
||
- 目录内仅保留本轮解析到的最新模块数据,避免历史目录残留影响结构一致性。
|
||
|
||
## 结构优化说明
|
||
|
||
- 入口脚本统一放在 `scripts/`。
|
||
- 数据统一放在 `data/`,减少根目录散落文件。
|
||
- 采用覆盖写入模式,避免重复历史文件导致目录混乱与资源浪费。
|