代码注释反向生成 API 文档站
🎯 解决什么问题
接口写完了文档永远欠着，新人接手只能啃源码。智能体扫描代码里的路由、参数校验和注释，生成 OpenAPI 规范，并渲染成可交互的文档站（含在线调试）。接口变更后重新跑一遍，文档自动同步更新。
😣 后端开发写完接口就赶下一个需求，文档永远“下周补”；新人接手对着上百个路由啃源码，一句“这个字段啥意思”在群里问三遍，联调全靠口口相传。
💡 API 文档从'永远欠着'变成随代码自动更新
🛠 操作步骤（共5步）
1
扫描代码与注释让智能体遍历仓库的路由定义、参数校验、注释和示例请求，用 Muse 或 Cursor 全仓理解接口的真实行为，而不是只看函数名猜。
2
生成 OpenAPI 规范输出 openapi.yaml，逐接口核对必填字段、枚举值、错误码是否齐全，含义模糊的字段打上 [待确认] 标记等人补。
3
渲染可交互文档站用 Swagger UI 或 Redoc 把规范渲染成支持在线调试的文档站，部署到 Vercel，联调时直接在页面上试请求。
4
接入 CI 自动同步在 GitHub Actions 里加一步：接口变更的 PR 合并后自动重跑生成，文档版本永远和代码版本对齐，告别“文档欠着”。
5
人工补业务语义机器填不出“为什么这样设计”，这部分由开发在 review 时补一句中文说明，重点写给外部调用方看。
📋 提示词模板（复制即用）
你是一名技术文档工程师。请扫描 [仓库路径/分支] 中的全部 API 路由，结合代码注释和参数校验逻辑，生成 OpenAPI 3.0 规范。要求：每个接口写清中文描述、请求/响应示例、错误码含义；字段名保持原样不翻译；含义模糊的字段标注 [待确认]。最后输出可直接渲染的 openapi.yaml，不要省略任何已发现的路由。
🧰 用到工具
Muse · Swagger · Vercel
⚠️ 注意事项
- 注释写得烂的代码生成出来也是烂文档，先统一注释规范再跑流水线，事半功倍。
- 鉴权、支付回调等敏感接口的文档站要加访问密码，别把内网接口裸奔到公网。
- 大仓先按模块分批生成，一次全扫容易超时或把不相关的内部接口也暴露出来。