从代码和OpenAPI生成API文档

要解决的问题

手写 API 文档常见的困境是：文档写完那一刻就已经过期。路由加了版本前缀没同步、参数校验规则改了没更新、错误码只存在于异常处理代码里没人整理。另一种极端是直接对着 OpenAPI 文件生成一堆没人读的机械描述，契约里缺的字段照样缺，甚至把生成产物误当成事实来源。

这个技能要解决的核心问题是：让文档有据可查，并且明确区分哪些是确认过的事实、哪些是推断。

核心能力

它的工作方式建立在明确的来源优先级之上，按可信度从高到低依次采用：

• 已入库的 OpenAPI/Swagger 契约和生成的 schema
• 框架路由定义与注解（支持 Spring、FastAPI、NestJS、Express、Gin）
• 请求/响应模型与校验规则
• 鉴权中间件、异常处理和错误目录
• 集成与契约测试
• 用户明确授权的运行时观察

当不同来源互相矛盾时，它不会静默选一个，而是把冲突报告出来。

工作流程

1. 检查：识别项目框架、模块、现有契约，区分生成产物与真实来源，确定文档范围
2. 构建端点清单：为每个端点捕获方法与完整路径、鉴权方案、请求字段与校验规则、响应 schema、错误码、证据出处
3. 解析 schema：展开嵌套模型和泛型响应包装，保留 nullable、enum、范围等约束，检测分页约定，对示例中的敏感数据做脱敏
4. 生成文档：沿用仓库已有的文档约定，或从模板复制；写入前会报告目标路径和文件是否已存在，脚本也不会覆盖已有输出，除非显式传入 --force
5. 验证：对照端点清单检查路由、对照校验器核对字段、对照代码核对状态码，并标记未解决的冲突和推断字段

证据标签与适用边界

文档中的每个结论都会带上证据标签：已确认：契约、已确认：源码、已确认：测试、推断 或 待确认。这保证读者知道哪些是确凿的、哪些还需要人工复核。

需要注意几点边界：它不会编造示例值、未记录的错误码、必填标记或响应字段——证据不足的端点会直接跳过并在完成报告里说明原因；除非 API 真的被运行过，否则不会声称做了运行时验证；生成的完成报告会列出更新的文件、端点数量、使用的来源、契约与源码的不一致之处、推断字段以及被跳过的端点。

适合的场景是代码库中有明确契约或规范框架的项目。如果你的 API 完全没有机器可读的定义、也没有任何校验规则和测试，产出的文档里会有大量 推断 标签，此时这份文档更适合作为起草底稿而非最终交付。