api-doc-generator

API Doc Generator

从代码自动生成 API 文档，支持 OpenAPI/Swagger 规范。

Overview

扫描项目代码中的路由和接口定义，自动提取参数、返回值、注释，生成符合 OpenAPI 3.0 规范的 YAML 文件和可交互的文档页面。

When to Use

• User wants to generate API documentation
• User mentions OpenAPI, Swagger, or API docs
• User has REST/GraphQL endpoints that need documentation
• User says "生成 API 文档" / "create API docs"
• User inputs /api-doc-generator

When NOT to Use:

• User only wants to write API descriptions in README
• User wants to test APIs (use testing tools)
• User's project has no HTTP endpoints
• User wants to generate SDK/client code
• User wants to mock APIs (use Mockoon, WireMock)

Core Pattern

Step 1: 检测框架和路由

# 快速检测
grep -rE "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（Handlebars 模板，含 {{variable}} 与 {{#each}} 占位符）作为基础。将提取的接口信息注入对应变量，渲染后输出 openapi.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:
                  $ref: '#/components/schemas/User'

Step 4: 生成交互式文档页面（可选）

使用 Swagger UI 或 Redoc 生成可浏览的 HTML 页面：

# 使用 npx 快速预览
npx @redocly/cli preview-docs openapi.yaml

Quick Reference

/api-doc-generator                    # 扫描当前项目，生成 openapi.yaml
/api-doc-generator --format yaml      # 输出 YAML（默认）
/api-doc-generator --format json      # 输出 JSON
/api-doc-generator --preview          # 生成并预览交互式文档

Common Mistakes