OpenAPI 规范生成器 (OpenAPI Spec Generator)

将原始的 API 接口信息转换为可直接用于生产的 OpenAPI 3.x 规范。支持从代码仓库、HAR 文件、流量日志或数据包捕获中导入数据，通过交互式调整，最终生成经过验证、可共享的规范文件。

核心能力

• 多源数据导入：支持从 Go/Java/Python/Node.js 代码、HAR 捕获、Charles Proxy 日志、Wireshark PCAP 文件，或手动输入的接口描述中生成规范
• 路由发现与聚类：扫描框架特定的路由定义（如 Gin、Spring、FastAPI、Express），并根据路径结构对相似接口进行聚类
• 模式推断：从代码结构体、样本数据或流量观察中推断请求/响应的 JSON 模式，包含类型、必填/可选、格式、枚举值及校验规则
• 认证信息提取：从代码注解、中间件逻辑或捕获的请求头中识别并记录认证方式（如 Bearer JWT、API Key、OAuth2、Basic Auth）
• 交互式优化：展示草稿规范 → 用户确认、修正或补充 → 重新生成 → 验证 → 循环迭代直至达到生产就绪状态
• OpenAPI 验证：使用官方 OpenAPI 验证工具检查规范，标记模式错误、缺失必填字段及不符合最佳实践的问题
• 模拟服务器生成：可选生成兼容 Prism 的模拟服务器配置，实现 API 的即时仿真

工作流程（共 8 步）

步骤 1：选择输入源

输入：用户选择一个或多个数据源：

• 代码仓库路径：包含 API 源码的本地目录
• HAR 文件：从 Chrome 开发者工具网络面板导出
• 流量日志：Charles Proxy 导出、mitmproxy 输出或自定义日志格式
• PCAP 文件：Wireshark 或 tcpdump 捕获的数据包
• 手动描述：自然语言形式的接口说明（例如：“POST /users 用于创建带姓名和邮箱的用户”）

输出：确认的输入源及其格式。若选择多个源，则采用合并模式（合并所有接口）。

步骤 2：接口发现

输入依据源类型：

• 代码源：扫描路由注册模式：

- Go（Gin）：router.GET("/users/:id", ...)

- Java（Spring）：@GetMapping("/users/{id}")

- Python（FastAPI）：@app.get("/users/{id}")

- Node（Express）：app.get('/users/:id', ...)

• HAR/日志源：解析日志条目，提取唯一的（方法, 路径）组合
• PCAP 源：从 TCP 流中重构 HTTP 请求；按（方法, 解析后的路径）去重

操作：对相似路径进行聚类以识别路径参数：

GET /users/1
GET /users/2
GET /users/42
→ GET /users/{id}

输出：接口列表：方法 + 路径模板 + 数量/置信度

步骤 3：请求/响应模式推断

输入：接口列表 + 原始数据

针对代码源：提取请求/响应结构体/类：

• Go：解析结构体标签（如 json:"name" binding:"required"）
• Java：解析 @RequestBody、@Valid 注解及 DTO 字段注解
• Python：解析 Pydantic 模型与类型提示
• Node：解析 Joi/Zod 校验规则或 TypeScript 接口

针对流量源：按接口聚合观测到的请求体与响应体，从样本中推断 JSON Schema：

• 识别字段类型（string、number、boolean、array、object）
• 识别必填字段（在所有样本中均出现）
• 识别枚举值（出现值有限）
• 识别格式（date-time、email、uri、uuid 等模式）
• 识别可为空字段（部分样本中出现 null）

输出：每个接口的请求模式 + 按状态码划分的响应模式。每项推断字段附带置信度评分。

步骤 4：参数分类

输入：接口列表 + 模式信息

操作：对参数进行分类：

• 路径参数：{id}、{userId} —— 从 URL 模板中提取
• 查询参数：?page=1&limit=20 —— 来自 HAR 中的查询字符串
• 请求头参数：Authorization、X-Request-ID、Content-Type
• Cookie 参数：来自捕获的 Cookie 头部
• 请求体：JSON 数据体或表单数据

输出：每个接口的完整参数列表，包含类型、位置、是否必填、描述（自动提取或来自代码注释）

步骤 5：认证机制检测

输入：代码注解或捕获的请求头

操作：识别认证模式：

• Bearer JWT：Authorization: Bearer eyJ... 请求头模式
• API Key：X-API-Key: ... 或 ?api_key=... 模式
• OAuth2：Authorization: Bearer ... + 代码中存在令牌刷新逻辑
• Basic Auth：Authorization: Basic ... 请求头
• 基于 Cookie：会话 Cookie 模式
• 无认证：所有捕获请求中均未出现认证头

输出：安全方案定义 + 应用到的接口列表

步骤 6：生成 OpenAPI 规范

输入：所有分析结果

操作：生成 OpenAPI 3.x YAML（默认）或 JSON 格式：

openapi: 3.0.3
info:
  title: {根据项目名称或用户输入推断}
  version: 1.0.0
servers:
  - url: {根据流量捕获或用户输入推断}
paths:
  /users/{id}:
    get:
      summary: 根据 ID 获取用户
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
      required: [id, name]

输出：OpenAPI 规范草稿文件

步骤 7：交互式优化

输入：规范草稿 + 用户反馈

操作：展示规范摘要：

• 总接口数：42
• 总模式数：18
• 认证方案：Bearer JWT
• 警告：3 个接口缺少响应模式，2 个模式包含低置信度字段

输出：用户可确认、修改或补充内容，系统重新生成并验证，进入下一轮迭代

步骤 8：输出与交付

输出：

• 最终版 OpenAPI 3.x 规范文件（YAML 或 JSON）
• 可选：生成 Prism 兼容的模拟服务器配置文件
• 可选：提供验证报告（含警告与建议）

技能：OpenAPI 规范生成器

版本：1.0.0

分块：2/3

用户可执行以下操作：

• 覆盖自动识别的标题、描述和服务器 URL
• 为特定端点添加描述和示例
• 标记被错误分类为必填/可选的字段
• 指定错误响应模式（生成器可能仅从 HAR 文件中看到 200 响应）
• 添加 API 级别元数据（联系人、许可证、服务条款）
• 为端点设置标签分组

输出：优化后的规范。每次修改后需重新生成并验证。

步骤 8：验证与导出

输入：已优化的 OpenAPI 规范

操作：

1. 执行 OpenAPI 结构验证（检查必填字段、模式引用、路径唯一性）
2. 执行最佳实践检查：所有端点均有描述，所有模式均有示例，无尾部斜杠
3. 可选：生成适用于 Swagger UI 的 HTML 预览
4. 导出为 YAML 或 JSON 文件
5. 可选：生成 Prism 模拟服务器配置：

# prism-config.yml
mock:
  dynamic: true
  cors: true

输出：已验证的 OpenAPI 规范文件 + 可选的模拟服务器配置

示例提示

提示 1：从代码仓库生成

用户：“从这个 Go 项目生成 OpenAPI 文档 [path: ~/projects/user-service/]”

期望输出：

发现 12 个端点，分布在 3 个路由组中：
  GET    /health
  GET    /api/v1/users
  POST   /api/v1/users
  GET    /api/v1/users/{id}
  PUT    /api/v1/users/{id}
  DELETE /api/v1/users/{id}
  ...
生成 5 个模式：User、CreateUserRequest、UpdateUserRequest、ErrorResponse、Pagination
认证方式：Bearer JWT（通过中间件检测）
草稿规范已保存：openapi.yaml（12 个端点，5 个模式）
警告：2 个端点缺少响应描述

提示 2：从 HAR 文件生成

用户：“我从浏览器导出了 HAR 文件，帮我生成 API 文档 [upload: api-capture.har]”

期望输出：

解析 HAR：共 287 个请求，涉及 3 个域名
去重后得到 23 个唯一端点
置信度：高（每个端点有多个样本）
14 个端点有 ≥5 个响应样本（模式推断：高置信度）
9 个端点有 1–4 个样本（模式推断：中等置信度）
草稿规范：openapi.yaml（23 个端点，31 个模式）
⚠️ 5 个端点仅捕获到 200 OK 响应（错误模式可能不完整）

提示 3：从手动描述生成

用户：“帮我写一个用户管理 API 的 OpenAPI 文档：注册、登录、获取个人信息、更新个人信息、注销账号”

期望输出：包含 5 个端点的完整 OpenAPI 规范，包含 User/AuthRequest/AuthResponse 模式、JWT 认证方案及标准错误响应。提供交互式优化选项。

提示 4：从流量日志生成

用户：“分析这个 Charles 抓包日志，生成 API 文档 [upload: charles-session.chls]”

期望输出：解析 Charles Proxy 会话导出 → 提取 HTTP 请求 → 去重 → 推断模式 → 生成规范。注意：二进制或 Protobuf 内容标记为“无法解析”。

提示 5：验证并改进现有规范

用户：“帮我检查这个 OpenAPI 文件有没有问题，并补充缺失的描述 [upload: api-spec.yaml]”

期望输出：验证报告：“3 个响应描述缺失，1 个 $ref 引用损坏，2 个模式缺少 'type' 字段。” 已修复版本：api-spec-v2.yaml。

提示 6：生成模拟服务器

用户：“基于刚生成的 OpenAPI 文档，生成一个模拟服务器配置”

期望输出：兼容 Prism 的配置文件 + docker-compose 启动片段。说明：“运行 docker-compose up，模拟 API 将在 http://localhost:4010 可访问。”

实际任务示例

示例 1：遗留系统文档化

场景：开发者接手一个五年历史的 Go 微服务，没有任何 API 文档。

输入：“这个老项目没有任何 API 文档，帮我从代码生成 [path: ~/projects/legacy-order-service/]”

步骤：

1. 扫描 Go 代码：识别 Gin 路由、结构体定义、中间件
2. 提取：18 个端点，12 个请求/响应结构体，JWT 认证 + Webhook 用 API Key
3. 通过 Go 结构体标签推断类型：json:"order_id" binding:"required" → 必填字段
4. 检测已弃用端点：注释 // DEPRECATED: use /v2/orders
5. 生成带弃用警告的规范
6. 用户审查：为 5 个命名晦涩的字段补充业务描述

输出：完整的 OpenAPI 规范 + “已弃用端点” 迁移指南

示例 2：第三方 API 逆向工程

场景：需要对接一个无文档的第三方 API。

输入：“对接第三方 API 没有文档，只有这个 HAR 文件 [upload: partner-api.har]”

步骤：

1. 解析 HAR 中的 412 个请求
2. 去重 → 得到 34 个唯一端点
3. 路径参数聚类：/orders/1001、/orders/1002 → /orders/{orderId}
4. 模式推断：CreateOrder 有 8 个样本 → 对必填字段推断置信度高
5. 认证检测：X-API-Key 头 + 自定义头中的 HMAC 签名
6. 警告：仅凭流量无法推断 HMAC 签名算法

输出：包含 34 个端点、模式和认证方案的规范。标记：“HMAC 签名算法未知 — 请与合作方确认”

示例 3：API 标准化

场景：团队希望在 3 个微服务间统一 API 设计规范。

输入：“我们有 3 个服务的 API，帮我生成统一的 OpenAPI 规范，检查不一致的地方”

步骤：

1. 分别为服务 A、B、C 生成规范
2. 跨服务分析：发现命名不一致（user_id vs userId vs userID）
3. 发现结构不一致（A 返回分页数据，B 返回数组）
4. 发现缺失标准端点（A 有健康检查，B 没有）
5. 生成统一规范，包含标准化命名 + 迁移建议

输出：统一规范 + 不一致问题报告 + 迁移计划

🚀 首次成功路径（3 步）

1. 步骤 1：运行 openapi-gen.sh scan ~/projects/user-service/ — 发现端点并识别框架
2. 步骤 2：运行 openapi-gen.sh infer ~/projects/user-service/ — 审查推断出的请求/响应模式
3. 步骤 3：运行 openapi-gen.sh generate ~/projects/user-service/ --output openapi.yaml — 生成已验证的 OpenAPI 3.x 规范

边界条件

OpenAPI 规范文档生成器

行为规则

错误处理

安全要求

• 本地处理：所有代码扫描、HAR 解析和模式推断均在本地运行。源代码和流量数据不会发送至外部服务。
• 禁止在规范中暴露密钥：自动清除流量样本或代码注释中发现的 API 密钥、令牌、密码及其他敏感信息。替换为 {{YOUR_API_KEY}} 占位符。
• 代码隐私保护：扫描的代码不会被存储或传输。中间分析数据在规范生成后立即丢弃。
• 流量数据敏感性：HAR 文件和 PCAP 可能包含认证令牌和个人身份信息。向用户发出警告。仅处理 URL 和模式元数据；在完成模式推断后从内存中移除请求/响应体。
• 规范文件安全性：生成的规范是设计文档，非可执行代码。其设计上不包含任何密钥。
• 内部网络数据处理：若 HAR/PCAP 包含内部主机名或 IP 地址，在共享规范前向用户发出警告。