WEB/workflows/api-doc-system
2026-04-15 21:01:12 +08:00
..
2026-04-15 21:01:12 +08:00
2026-04-15 21:01:12 +08:00
2026-04-15 21:01:12 +08:00
2026-04-15 21:01:12 +08:00
2026-04-15 21:01:12 +08:00
2026-04-15 21:01:12 +08:00
2026-04-15 21:01:12 +08:00
2026-04-15 21:01:12 +08:00
2026-04-15 21:01:12 +08:00
2026-04-15 21:01:12 +08:00

API Doc System Workflow

该工作流用于自动抓取 system API 文档页面,按 platform=网页端(web)、project=全部(all) 条件进行校验后,清洗输出模块与接口数据。

目录结构

  • config.mjs: 抓取地址、筛选条件、输出目录、保留天数配置。
  • update.mjs: 抓取、解析、清洗、落盘、历史清理的一体化脚本。
  • clear-pending.mjs: 清空 pending-updates.json 的辅助脚本。
  • cleanup-marked.mjs: 清理已标记删除的模块与接口,并重置待更新记录。
  • module/: 按模块分文件夹存储,每个模块每天一份文件(YYYYMMDD.json)。[接口详细配置信息]
  • module-list/: 每天一份模块总览文件(YYYYMMDD.json)。[接口快速一览]
  • interface-details/: 全量接口明细归档文件(YYYYMMDD.json,按日更新)。[归档记录]
  • pending-updates.json: 待更新文件(模块变化 + 接口变化 + 兼容 legacy 结构)。[待更新接口信息]
  • pending-history/: 待更新历史快照(YYYYMMDDHHmmss.json,保留最近 5 个版本)。[历史快照]

运行

npm run apiconfig

如需清空待更新接口文件,可执行:

npm run apiconfig:clear-pending

如需清理“已标记删除”的模块与接口,可执行:

npm run apiconfig:clean-marked

执行前会先检查 pending-updates.json:

  • 若存在未处理项,脚本会输出:
    • 还有未更新接口等待处理!请处理待更新接口再执行此程序。
  • 并终止本次执行,不更新其他产物。

如需改抓取地址,可临时指定:

API_DOC_URL=http://192.168.11.56:6060/api/docs/system npm run apiconfig

输出说明

  • 模块文件包含当前模块全部接口信息(接口名、描述、Headers、Params、Response 等)。
  • module 是最新接口信息的主数据源,每次执行 npm run apiconfig 都会更新当日模块文件。
  • 每个模块快照新增 changes.fromPreviousSnapshot 字段,记录本模块相对上一快照的:
    • 模块是否新增/重命名
    • 接口新增/删除
    • 接口 params 更新
    • 接口 response 更新
  • 每份模块快照新增 versionWindow,用于展示最近 5 个版本窗口(受保留天数控制)。
  • 模块总览文件仅保留每个模块的精简接口清单:
    • method
    • isUsed
    • isPlaceholder
  • module-list 与 interface-details 均新增 changes 字段,统一汇总模块与接口变化统计:
    • moduleUpdates.added / deleted / updated / split / merged / replaced
    • interfaceUpdates.added / deleted / paramsUpdated / responseUpdated
  • 接口明细文件包含当前项目所有接口信息,并带状态字段:
    • status.isUsed: 是否使用(默认 false)
    • status.isPlaceholder: 是否占位(默认 false)
  • 状态会优先继承 module 目录最近快照中的状态,避免每次执行覆盖人工维护状态。
  • module-list、interface-details、pending-updates 均包含 versionWindow 字段,用于展示最近 5 版本窗口信息。
  • 脚本输出增加本地可读时间字段(如 generatedAtLocal),终端日志统一显示 YYYY-MM-DD HH:mm:ss。
  • 页面中的 platform/project 是全局请求头配置项,脚本会校验 web/all 选项存在,并将其写入每份产物的 filter 字段。
  • pending-updates.json 中:
    • summary:变化统计汇总
    • moduleUpdates:模块级变化(含拆分、合并)
    • interfaceUpdates:接口级变化
    • legacy:兼容旧结构(按模块聚合 methods)

待更新接口判定规则

  • 与上一轮有效快照对比后,以下变化会写入 pending-updates.json:
    • 模块更新:新增模块、删除模块、模块替换、旧模块拆分为多个新模块、多个旧模块合并为新模块
    • 接口更新:新增接口、删除接口、params 变化、response 变化
  • 同时会写入 pending-history/,用于保留最近 5 个待更新版本。

模块文件夹生命周期

  • 新模块首次出现时自动创建模块文件夹并生成 _module.lifecycle.json。
  • 当模块在最新文档中消失时,不删除模块文件夹,而是在该目录新增 _deleted.YYYYMMDD.json 删除标记,并将生命周期状态更新为 deleted。
  • 若后续文档再次出现该模块,会自动恢复为 active,保留历史标记用于回退排查。
  • 若确认无需保留回退数据,可执行 npm run apiconfig:clean-marked 物理删除已标记模块,并清理待删接口。

历史保留(最近 5 版本)

  • module/*/YYYYMMDD.json、module-list/YYYYMMDD.json、interface-details/YYYYMMDD.json 自动保留最近 5 天快照。
  • pending-history/YYYYMMDDHHmmss.json 自动保留最近 5 个版本快照。
  • 如需调整保留数量,可修改 config.mjs 中 retentionDays。