api-doc-generator

API 文档生成器

根据权威资料编写 API 文档，并区分已确认事实与推断。

来源优先级

按以下顺序使用可用的最强来源：

1. 已纳入版本控制的 OpenAPI/Swagger 契约和生成的架构。
2. 框架路由定义和注解。
3. 请求/响应模型和验证规则。
4. 身份验证、中间件、异常处理和错误目录。
5. 集成测试和契约测试。
6. 用户明确授权的运行时观察结果。

如果来源之间存在分歧，应报告不一致，而不是默默选取其中一个。

框架路由

仅阅读相关参考资料：

• OpenAPI 优先：references/openapi-first.md
• Java/Kotlin Spring：references/spring.md
• Python FastAPI：references/fastapi.md
• TypeScript NestJS：references/nestjs.md
• JavaScript/TypeScript Express：references/express.md
• Go Gin：references/gin.md

仅在需要完整示例时使用 references/scan-and-generate-example.md。

对于已纳入版本控制的 OpenAPI 文档，在撰写说明前先生成确定性清单：

python3 scripts/inventory_openapi.py path/to/openapi.yaml --output docs/api-inventory.md

除非明确提供 --force，否则脚本不会覆盖已有输出。

工作流

1. 检查

1. 检测项目框架、模块、现有 API 契约和文档规范。
2. 根据用户的表述确定请求范围；只有在没有更具体范围时，才推断为整个 API。
3. 查找路由注册、基础路径、版本前缀、安全中间件、模型、验证器、错误处理和测试。
4. 识别生成的文件，以免将其误认为事实来源。

2. 建立端点清单

为每个端点记录：

字段	要求
方法和路径	解析所有前缀和路由组
操作标识	处理器/控制器和稳定的操作名称
用途	根据代码/注释推导；标明推断
身份验证	方案、范围/角色和公开访问例外
请求	路径/查询/标头/ Cookie /请求体字段和验证规则
响应	状态码、内容类型、架构和包装结构
错误	仅记录处理器、中间件、测试或目录支持的错误
依据	所使用的契约或源码位置

不得编造示例值、未记录的错误代码、必填标记或响应字段。

3. 解析架构

• 跟踪嵌套模型引用和泛型响应包装结构。
• 保留可空性、可选性、枚举、格式、范围和长度约束。
• 检测分页和列表封装惯例。
• 明确展示递归或多态架构。
• 在示例中隐去机密和个人数据。

4. 生成文档

遵循仓库现有规范。如果没有规范，从 assets/templates/ 复制一个模板，并写入 docs/ 下建议的路径。写入前，报告目标路径以及该文件是否已存在。

每个端点都必须包含：

1. 摘要和证据状态
2. 方法和完整路径
3. 身份验证/授权
4. 参数和请求体
5. 响应和有依据的错误
6. 最简有效示例
7. 源码位置

5. 验证

• 将文档中的路由与已发现的清单进行比较。
• 根据验证器/模型核实路径变量和请求字段。
• 根据代码或契约核实响应和错误状态码。
• 检查内部链接和锚点。
• 标明未解决的冲突和推断字段。
• 除非实际运行过 API，否则不得声称已完成运行时验证。

证据标签

需要明确确定性时，请使用以下标签：

• 已确认：契约 — 存在于已检入的 API 契约中。
• 已确认：源码 — 存在于路由／模型／处理程序源码中。
• 已确认：测试 — 已由测试验证。
• 推断 — 合理，但未明确说明。
• 待确认 — 证据冲突或缺失。

完成契约

报告已生成／更新的文件、已记录的端点数量、使用的权威来源、契约／源码不一致之处、推断的字段，以及因证据不足而跳过的端点。