api-doc-generatorlisted

# API Doc Generator 从代码自动生成 API 文档，支持 OpenAPI/Swagger 规范。 ## Overview 扫描项目代码中的路由和接口定义，自动提取参数、返回值、注释，生成符合 OpenAPI 3.0 规范的 YAML 文件和可交互的文档页面。 ## When to Use - 用户想给项目生成 API 文档 - 用户提到 OpenAPI、Swagger、API 文档 - 用户有 REST/GraphQL 接口需要文档化 - 用户输入 `/api-doc-generator` **When NOT to Use:** - 用户只是想写 README 里的 API 说明 - 用户想做 API 测试（那是另一个 skill） - 用户的项目没有 HTTP 接口 ## Core Pattern ### Step 1: 检测框架和路由 | 框架 | 检测方式 | 路由提取 | |------|---------|---------| | Express/Koa/Fastify | `require('express')` / 路由文件 | 扫描 `app.get/post/put/delete` | | Next.js API Routes | `app/api/` 目录 | 扫描 `route.ts` 文件 | | Gin (Go) | `r.GET/POST` | 扫描 `router` 注册 | | Flask/FastAPI (Python) | `@app.route` / `@router` | 扫描装饰器 | | Spring Boot (Java) | `@GetMapping` / `@RestController` | 扫描注解 | ```bash # 快速检测 grep -r "app\.\(get\|post\|put\|delete\|patch\)" --include="*.ts" --include="*.js" --include="*.go" --include="*.py" -l ``` ### Step 2: 提取接口信息 对每个路由提取： - **HTTP Method + Path** - **请求参数**：query、params、body（从类型定义/JSDoc/注解推断） - **响应格式**：从 return 语句或类型定义推断 - **注释/描述**：从代码注释提取 - **认证要求**：检查是否有 auth middleware ### Step 3: 生成 OpenAPI YAML 使用 `templates/openapi.yaml` 作为基础结构，填充提取的信息： ```yaml openapi: 3.0.3 info: title: 项目名 API version: 1.0.0 paths: /api/users: get: summary: 获取用户列表 parameters: [...] responses: '200': description: 成功 content: application/json: schema: type: array items: $re