用途
API Doc Generator 用于从已有代码自动生成 API 文档，输出符合 OpenAPI/Swagger 规范的 YAML 或 JSON 文件。它扫描项目代码中的路由和接口定义，自动提取参数、返回值、注释，生成 OpenAPI 3.0 规范文件，并可选生成可交互的文档页面。
主要能力
- 检测框架和路由：支持 Express/Koa/Fastify（扫描 app.get/post/put/delete）、Next.js API Routes（扫描 app/api/ 目录下的 route.ts 文件）、Gin（Go，扫描 router 注册）、Flask/FastAPI（Python，扫描装饰器）、Spring Boot（Java，扫描注解）。
- 提取接口信息：对每个路由提取 HTTP Method + Path、请求参数（query、params、body，从类型定义/JSDoc/注解推断）、响应格式（从 return 语句或类型定义推断）、注释/描述（从代码注释提取）、认证要求（检查是否有 auth middleware）。
- 生成 OpenAPI YAML：使用 templates/openapi.yaml（Handlebars 模板，含 {{variable}} 与 {{#each}} 占位符）作为基础，将提取的接口信息注入对应变量，渲染后输出 openapi.yaml。
- 生成交互式文档页面（可选）：使用 Swagger UI 或 Redoc 生成可浏览的 HTML 页面。
使用方式
命令形式：
- /api-doc-generator：扫描当前项目，生成 openapi.yaml
- /api-doc-generator --format yaml：输出 YAML（默认）
- /api-doc-generator --format json：输出 JSON
- /api-doc-generator --preview：生成并预览交互式文档
参数说明：
- --format：输出格式 yaml / json，默认 yaml
- --preview：生成交互式 HTML 文档，默认 false
快速检测命令示例：
grep -rE "app.(get|post|put|delete|patch)" --include=".ts" --include=".js" --include=".go" --include=".py" -l
预览命令示例：
npx @redocly/cli preview-docs openapi.yaml
适用场景
- 用户想要生成 API 文档
- 用户提到 OpenAPI、Swagger 或 API docs
- 用户有需要文档化的 REST/GraphQL 端点
- 用户输入“生成 API 文档”/“create API docs”
- 用户输入 /api-doc-generator
限制与不适用场景
- 用户只想在 README 中写 API 描述
- 用户想测试 API（应使用测试工具）
- 用户的项目没有 HTTP 端点
- 用户想生成 SDK/客户端代码
- 用户想 mock API（应使用 Mockoon、WireMock）
常见错误与正确做法
- 只扫描一个文件 → 递归扫描所有路由文件（可能遗漏接口）
- 硬编码请求体结构 → 从类型定义推断（保持文档与代码一致）
- 不处理嵌套路由 → 分析路由注册的完整路径（/api/users/:id 的 :id 需要标注）
- 忽略错误响应 → 添加 4xx/5xx 响应（完整的 API 文档需要错误说明）
- 忽略认证要求 → 检查 auth middleware（客户端需要知道哪些接口需要认证）