Skill: Swagger/OpenAPI 文档生成

从项目源代码自动分析并生成 Swagger/OpenAPI 3.0 规范文档。

触发条件

当用户请求以下操作时激活：

"生成 swagger"、"生成 api 文档"、"generate swagger"、"generate openapi"
"给这个项目加 swagger"、"写 api docs"
对现有项目需要 API 文档输出

执行步骤

第一步：检测项目类型和框架

使用 Glob 工具搜索项目根目录下的 package.json、pyproject.toml、requirements.txt、go.mod、Cargo.toml、pom.xml、build.gradle，确定项目语言
JS/TS 框架检测：使用 Grep 工具在 package.json 中搜索 express|fastify|koa|hono|nest|next|nuxt|elysia 依赖
Python 框架检测：使用 Grep 工具在 requirements.txt 和 pyproject.toml 中搜索 fastapi|flask|django|tornado|sanic
Go 框架检测：使用 Grep 工具在 go.mod 中搜索 gin|echo|fiber|chi|mux
Java 框架检测：使用 Grep 工具在 pom.xml 或 build.gradle 中搜索 spring-boot|spring-web|jersey|jax-rs

根据检测结果确定：

语言 + 框架组合
路由定义方式（装饰器/链式/配置文件）
现有 swagger/openapi 配置（可能已有部分文档）

第二步：扫描 API 路由

根据框架类型，使用不同策略扫描路由：

Next.js App Router: 使用 Glob 工具搜索 src/app/api/**/route.{ts,js} 模式，找到所有 API 路由文件

Django (Python): 使用 Grep 工具在 urls.py 文件中搜索 path\(|re_path\( 模式（排除 migrations 目录）

Spring Boot (Java): 使用 Grep 工具搜索 @GetMapping|@PostMapping|@PutMapping|@DeleteMapping|@RequestMapping 模式，限定 .java 文件

第三步：分析每个端点

对每个发现的路由，阅读源代码提取：

路径和方法 — GET /api/users/:id
请求参数：
- Path params（路径参数）
- Query params（查询参数）
- Request body（请求体 schema）
- Headers（自定义 header）
响应格式：
- 成功响应的 status code 和 body schema
- 错误响应（400、401、404、500 等）
认证方式 — Bearer token、API key、Cookie 等
中间件 — 权限校验、rate limiting 等

提取类型信息的优先级：

TypeScript 类型/接口定义（最可靠）
Zod/Joi/Yup 等校验 schema
Pydantic model（Python）
struct tag（Go）
Rust serde 序列化注解（#[derive(Serialize, Deserialize)]、#[serde(rename_all = "camelCase")] 等）
实际响应代码中的字面量

第四步：检查现有文档

使用 Glob 工具搜索 **/swagger.*、**/openapi.*、**/api-docs.* 模式（排除 node_modules 目录），同时检查 docs/ 和 doc/ 目录下是否有 api* 文件

若已有文档，读取并作为基础进行增量更新，而非从零生成。

增量更新流程：

解析现有 openapi.yaml，提取已有的所有 operationId 和路径列表
扫描源代码找出新增和已删除的端点（与现有文档对比）
新增端点：追加到 paths 中，生成完整定义
已删除端点：不直接移除，标注 deprecated: true 保留向后兼容
已有端点：只更新引用的 schema 定义（如字段类型变化），保留手工修改的 description、example 等内容

第五步：生成 OpenAPI 3.0 文档

OpenAPI 版本选择：

3.0.3（默认）：广泛支持，工具生态成熟（swagger-ui、redocly、codegen 等均兼容）
3.1（可选）：更好的 JSON Schema 支持（如 null 类型），但部分工具兼容性有限，选用前需确认下游工具链支持

生成 YAML 格式的 OpenAPI 规范文件，结构如下：

openapi: 3.0.3
info:
  title: <项目名称> API
  description: <从 README 或代码注释提取>
  version: <从 package.json/pyproject.toml 提取，默认 1.0.0>

servers:
  # ⚠️ 请根据项目实际情况确认并修改以下服务器地址
  - url: http://localhost:3000
    description: Development server (按项目实际端口配置)
  - url: https://api.example.com
    description: Production server (按实际域名替换)

paths:
  /api/example:
    get:
      summary: <简明描述>
      description: <详细描述>
      operationId: <唯一操作 ID>
      tags:
        - <按业务模块分组>
      parameters: [...]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExampleResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized

components:
  schemas:
    ExampleResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

第六步：输出文件

默认输出位置（按优先级）：

docs/openapi.yaml — 若 docs/ 目录已存在
openapi.yaml — 项目根目录

若用户指定了输出格式（JSON），则输出 openapi.json。

第七步：验证文档

使用 Bash 工具执行验证命令：

优先使用 bunx @apidevtools/swagger-cli validate openapi.yaml 验证文档格式
使用 bunx @redocly/cli lint openapi.yaml 进行规范检查
若 bunx 不可用，回退到 npx

若验证失败，修复问题后重新验证。

第八步：可选 - 集成 Swagger UI

如果用户需要在线浏览 API 文档，根据框架提供集成方案：

Express/Fastify: 使用 Bash 工具执行 bun add swagger-ui-express 安装依赖

FastAPI: FastAPI 自带 /docs 和 /redoc，只需确保 OpenAPI schema 正确加载。

Next.js: 建议使用 next-swagger-doc 或在 /api-docs 路由中嵌入 Swagger UI。

Spring Boot: 在 pom.xml 或 build.gradle 中添加 springdoc-openapi 依赖

完成总结

所有步骤完成后，输出以下总结信息：

📋 Swagger/OpenAPI 文档生成完成
──────────────────────────────
发现端点数：<N> 个（GET: x, POST: y, PUT: z, DELETE: w）
生成 Schema 数：<N> 个
验证结果：✅ 通过 / ❌ 失败（附失败原因）
输出文件：<文件路径>
──────────────────────────────
后续步骤建议：
- [ ] 人工检查 description 和 example 是否准确
- [ ] 确认 servers 地址是否正确
- [ ] 如需在线浏览，参考第八步集成 Swagger UI
- [ ] 将生成的文档提交到版本控制

Schema 生成规则

类型映射

源代码类型	OpenAPI 类型
`string`	`type: string`
`number` / `float` / `double`	`type: number`
`int` / `integer`	`type: integer`
`boolean` / `bool`	`type: boolean`
`Date` / `datetime`	`type: string, format: date-time`
`Array<T>` / `T[]` / `[]T`	`type: array, items: {$ref}`
`object` / `Record` / `map`	`type: object`
`null` / `None` / `nil`	`nullable: true`
`enum`	`type: string, enum: [...]`
`File` / `UploadFile`	`type: string, format: binary`

文件上传端点处理

检测以下特征识别文件上传：

参数类型包含 UploadFile / File / MultipartFile
装饰器或注解标注了 @FormParam / multipart
Content-Type 包含 multipart/form-data

生成时使用：

requestBody:
  required: true
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          file:
            type: string
            format: binary

命名约定

Schema 名称使用 PascalCase：UserResponse、CreateOrderRequest
operationId 使用 camelCase：getUserById、createOrder
tags 按业务模块分组：Users、Orders、Auth

必填字段判定

按以下规则判断字段是否 required：

TypeScript 中无 ? 的属性 → required
Zod 中未调用 .optional() 的字段 → required
Pydantic 中无默认值的字段 → required
Go struct 中无 omitempty tag 的字段 → required

质量检查清单

生成完成后，按优先级自检以下项目：

🔴 关键项（必须通过）：

所有 API 端点都已覆盖
所有 $ref 引用都有对应的 schema 定义
文档通过 lint 验证（swagger-cli / redocly）

🟡 重要项（强烈推荐）：

请求参数类型准确（path/query/body/header）
认证方式已正确标注
operationId 唯一且有意义
响应 schema 与实际代码匹配

🟢 可选项：

description 和 summary 清晰简洁
无遗漏的错误响应码（至少包含 400、500）

注意事项

不要凭空编造 API 端点，必须基于实际源代码
不要遗漏错误响应，至少包含 400 和 500
不要忽略认证中间件，确保 security 字段正确
不要在 schema 中使用 any 或过于宽泛的类型
若项目已有 swagger 装饰器/注解（如 @ApiProperty），优先从注解提取
大型项目（50+ 端点）建议分模块生成，使用 tags 分组
生成后建议提交到版本控制，方便后续维护

安全检查

文档中没有硬编码的 API key 或 secret
认证端点已标注 securitySchemes
敏感数据（密码、token）不在示例值中暴露
所有需认证的端点都标注了 security 要求

决策流程图

检测项目类型和框架
        |
扫描 API 路由定义
        |
是否找到路由？
  否 -> 提示用户确认 API 文件位置
  是 |
        |
检查是否已有 openapi/swagger 文件
  是 -> 增量更新模式
  否 -> 全量生成模式
        |
逐个分析端点：路径、参数、响应、认证
        |
提取/推断 schema 类型
        |
生成 openapi.yaml
        |
验证文档（swagger-cli / redocly）
  失败 -> 修复后重新验证
  通过 |
        |
输出结果 + 质量检查报告

swagger-gen