api-doc-generator

API Doc Generator

Automatically generate API documentation from code, supporting the OpenAPI/Swagger specification.

Overview

Scan routes and interface definitions in the project code, automatically extract parameters, return values, and comments, and generate YAML files compliant with the OpenAPI 3.0 specification and interactive documentation pages.

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: Detect framework and routes

Framework	Detection method	Route extraction
Express/Koa/Fastify	`require('express')` / route files	Scan `app.get/post/put/delete`
Next.js API Routes	`app/api/` directory	Scan `route.ts` files
Gin (Go)	`r.GET/POST`	Scan `router` registration
Flask/FastAPI (Python)	`@app.route` / `@router`	Scan decorators
Spring Boot (Java)	`@GetMapping` / `@RestController`	Scan annotations

# 快速检测
grep -rE "app\.(get|post|put|delete|patch)" --include="*.ts" --include="*.js" --include="*.go" --include="*.py" -l

Step 2: Extract interface information

For each route, extract:

HTTP Method + Path
Request parameters: query, params, body (inferred from type definitions/JSDoc/annotations)
Response format: inferred from return statements or type definitions
Comments/description: extracted from code comments
Authentication requirements: check whether there is auth middleware

Step 3: Generate OpenAPI YAML

Use templates/openapi.yaml(Handlebars template, containing {{variable}} and {{#each}} placeholders) as the basis. Inject the extracted interface information into the corresponding variables, and after rendering output openapi.yaml. The rendering result is roughly as follows:

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: Generate interactive documentation page (optional)

Use Swagger UI or Redoc to generate a browsable HTML page:

# 使用 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          # 生成并预览交互式文档

Parameter	Description	Default value
`--format`	Output format yaml / json	yaml
`--preview`	Generate interactive HTML documentation	false

Common Mistakes

Error	Correct approach	Reason
Scan only one file	Recursively scan all route files	Interfaces may be missed
Hard-code the request body structure	Infer from type definitions	Keep documentation consistent with code
Do not handle nested routes	Analyze the full path of route registration	`/api/users/:id` of `:id` needs to be annotated
Ignore error responses	Add 4xx/5xx responses	Complete API documentation requires error descriptions
Ignore authentication requirements	Check auth middleware	Clients need to know which interfaces require authentication