API 文档生成器

通过分析源代码，自动生成全面的 API 文档。自动提取端点（endpoints）、参数、请求/响应结构（schema）、认证要求，并生成示例。支持 Express、FastAPI、Django REST Framework、Rails、Spring Boot 等多种框架。

使用方式

"基于我的 Express 应用生成 API 文档"
"创建 API 参考文档"
"为本项目中的所有端点生成文档"
"从我的代码中生成 OpenAPI 规范"

工作原理

1. 框架识别

# 根据依赖文件识别框架
cat package.json 2>/dev/null | python3 -c "
import json,sys
d=json.load(sys.stdin).get('dependencies',{})
for fw in ['express','fastify','koa','hapi','nestjs','next']:
    if fw in str(d): print(f'Node: {fw}')
" 2>/dev/null

cat requirements.txt setup.py pyproject.toml 2>/dev/null | grep -i "fastapi|django|flask|starlette"

2. 端点提取

扫描源代码中的路由定义：

Express/Node：

grep -rn "router.(get|post|put|patch|delete|all)|app.(get|post|put|patch|delete)" src/ routes/

FastAPI/Python：

grep -rn "@app.(get|post|put|patch|delete)|@router.(get|post|put|patch|delete)" src/ app/

Django REST Framework：

grep -rn "class.*ViewSet|class.*APIView|path(" */views.py */urls.py

对每个端点，提取以下信息：

• HTTP 方法与路径
• URL 参数和查询参数
• 请求体结构（来自 TypeScript 类型、Pydantic 模型、序列化器等）
• 响应格式与状态码
• 认证要求
• 中间件链（middleware chain）
• 限流规则（rate limiting rules）

3. 结构（Schema）提取

分析类型定义或模型以获取请求/响应结构：

• TypeScript 接口（interfaces）与类型（types）
• 带字段校验器的 Pydantic 模型
• 含字段定义的 Django 序列化器（serializers）
• Joi/Zod 校验结构
• JSON Schema 定义

4. 示例生成

生成真实、可用的请求/响应示例：

• 包含所有必填字段的有效请求
• 含合理数据的响应
• 错误响应示例（400、401、403、404、500）
• 用于快速测试的 curl 命令
• 主流语言的 SDK 调用示例

5. 文档输出

支持多种格式输出：

Markdown API 参考文档：

## POST /api/users

创建新用户账户。

**认证：** 需要 Bearer token  
**限流：** 每分钟最多 10 次请求

### 请求体
| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| email | string | 是 | 合法邮箱地址 |
| name | string | 是 | 全名（2–100 字符） |
| role | enum | 否 | "user" 或 "admin"（默认值："user"） |

### 响应（201 Created）
```json
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "Jane Smith",
  "role": "user",
  "createdAt": "2026-04-30T10:00:00Z"
}

错误码

• 400 — 邮箱格式非法或缺少必填字段
• 409 — 邮箱已被注册
• 429 — 超出限流阈值

**OpenAPI 3.1 规范** — 机器可读格式，兼容 Swagger UI、Redoc、Postman

### 6. 完整性检查

验证文档质量：
- 所有端点均已记录
- 所有参数均有说明
- 响应结构与实际响应一致
- 认证方式已明确标注
- 错误码已完整列出
- 示例存在且有效

## 输出

已生成 API 文档

框架： Express.js + TypeScript 发现端点数： 23 文档完整性： 87%

生成的文件

• docs/api-reference.md（完整 Markdown 格式参考文档）
• docs/openapi.yaml（OpenAPI 3.1 规范）
• docs/examples/（各端点对应的 curl 示例）

覆盖率

未文档化的端点

• PATCH /api/users/:id — 已定义路由，但无类型注解
• POST /api/webhooks/stripe — 使用原始 req.body，无结构定义