api-documentation-generator

API 文档生成器

概述

从你的代码库自动生成清晰、全面的 API 文档。此技能可帮助你创建专业文档，包含端点描述、请求/响应示例、认证详情、错误处理和使用指南。

非常适合 REST API、GraphQL API 和 WebSocket API。

何时使用此技能

• 当你需要为新 API 编写文档时使用
• 当更新现有 API 文档时使用
• 当你的 API 缺少清晰文档时使用
• 当让新开发者熟悉你的 API 时使用
• 当为外部用户准备 API 文档时使用
• 当创建 OpenAPI/Swagger 规范时使用

工作原理

步骤 1：分析 API 结构

首先，我会检查你的 API 代码库，以了解：

• 可用的端点和路由
• HTTP 方法（GET、POST、PUT、DELETE 等）
• 请求参数和请求体结构
• 响应格式和状态码
• 认证和授权要求
• 错误处理模式

步骤 2：生成端点文档

对于每个端点，我会创建包含以下内容的文档：

端点详情：

• HTTP 方法和 URL 路径
• 功能简要描述
• 认证要求
• 速率限制信息（如适用）

请求规范：

• 路径参数
• 查询参数
• 请求头
• 请求体 schema（包含类型和验证规则）

响应规范：

• 成功响应（状态码 + 响应体结构）
• 错误响应（所有可能的错误码）
• 响应头

代码示例：

• cURL 命令
• JavaScript/TypeScript（fetch/axios）
• Python（requests）
• 其他语言（按需）

步骤 3：添加使用指南

我会包含：

• 入门指南
• 认证设置
• 常见用例
• 最佳实践
• 速率限制详情
• 分页模式
• 过滤和排序选项

步骤 4：记录错误处理

清晰的错误文档，包括：

• 所有可能的错误码
• 错误消息格式
• 故障排查指南
• 常见错误场景和解决方案

步骤 5：创建交互式示例

在可能的情况下，我会提供：

• Postman 集合
• OpenAPI/Swagger 规范
• 交互式代码示例
• 示例响应

示例

示例 1：REST API 端点文档

## Create User

Creates a new user account.

**Endpoint:** `POST /api/v1/users`

**Authentication:** Required (Bearer token)

**Request Body:**
\`\`\`json
{
  "email": "[email protected]",      // Required: Valid email address
  "password": "SecurePass123!",     // Required: Min 8 chars, 1 uppercase, 1 number
  "name": "John Doe",               // Required: 2-50 characters
  "role": "user"                    // Optional: "user" or "admin" (default: "user")
}
\`\`\`

**Success Response (201 Created):**
\`\`\`json
{
  "id": "usr_1234567890",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2026-01-20T10:30:00Z",
  "emailVerified": false
}
\`\`\`

**Error Responses:**

- `400 Bad Request` - Invalid input data
  \`\`\`json
  {
    "error": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "field": "email"
  }
  \`\`\`

- `409 Conflict` - Email already exists
  \`\`\`json
  {
    "error": "EMAIL_EXISTS",
    "message": "An account with this email already exists"
  }
  \`\`\`

- `401 Unauthorized` - Missing or invalid authentication token

**Example Request (cURL):**
\`\`\`bash
curl -X POST https://api.example.com/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!",
    "name": "John Doe"
  }'
\`\`\`

**Example Request (JavaScript):**
\`\`\`javascript
const response = await fetch('https://api.example.com/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'SecurePass123!',
    name: 'John Doe'
  })
});

const user = await response.json();
console.log(user);
\`\`\`

**Example Request (Python):**
\`\`\`python
import requests

response = requests.post(
    'https://api.example.com/api/v1/users',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'email': '[email protected]',
        'password': 'SecurePass123!',
        'name': 'John Doe'
    }
)

user = response.json()
print(user)
\`\`\`

示例 2：GraphQL API 文档

## User Query

Fetch user information by ID.

**Query:**
\`\`\`graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    email
    name
    role
    createdAt
    posts {
      id
      title
      publishedAt
    }
  }
}
\`\`\`

**Variables:**
\`\`\`json
{
  "id": "usr_1234567890"
}
\`\`\`

**Response:**
\`\`\`json
{
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "[email protected]",
      "name": "John Doe",
      "role": "user",
      "createdAt": "2026-01-20T10:30:00Z",
      "posts": [
        {
          "id": "post_123",
          "title": "My First Post",
          "publishedAt": "2026-01-21T14:00:00Z"
        }
      ]
    }
  }
}
\`\`\`

**Errors:**
\`\`\`json
{
  "errors": [
    {
      "message": "User not found",
      "extensions": {
        "code": "USER_NOT_FOUND",
        "userId": "usr_1234567890"
      }
    }
  ]
}
\`\`\`

示例 3：认证文档

## Authentication

All API requests require authentication using Bearer tokens.

### Getting a Token

**Endpoint:** `POST /api/v1/auth/login`

**Request:**
\`\`\`json
{
  "email": "[email protected]",
  "password": "your-password"
}
\`\`\`

**Response:**
\`\`\`json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "refreshToken": "refresh_token_here"
}
\`\`\`

### Using the Token

Include the token in the Authorization header:

\`\`\`
Authorization: Bearer YOUR_TOKEN
\`\`\`

### Token Expiration

Tokens expire after 1 hour. Use the refresh token to get a new access token:

**Endpoint:** `POST /api/v1/auth/refresh`

**Request:**
\`\`\`json
{
  "refreshToken": "refresh_token_here"
}
\`\`\`

最佳实践

✅ 应该这样做

• 保持一致 - 对所有端点使用相同格式
• 包含示例 - 提供多种语言的可用代码示例
• 记录错误 - 列出所有可能的错误码及其含义
• 展示真实数据 - 使用真实的示例数据，而不是 "foo" 和 "bar"
• 解释参数 - 描述每个参数的作用及其约束
• 为 API 添加版本 - 在 URL 中包含版本号（/api/v1/）
• 添加时间戳 - 显示文档最后更新时间
• 链接相关端点 - 帮助用户发现相关功能
• 包含速率限制 - 记录任何速率限制策略
• 提供 Postman 集合 - 让测试你的 API 变得简单

❌ 不要这样做

• 不要跳过错误情况 - 用户需要知道可能出现什么问题
• 不要使用模糊描述 - "获取数据" 没有帮助
• 不要忘记认证 - 始终记录认证要求
• 不要忽略边界情况 - 记录分页、过滤、排序
• 不要让示例失效 - 测试所有代码示例
• 不要使用过时信息 - 保持文档与代码同步
• 不要过度复杂化 - 保持简单且易于浏览
• 不要忘记响应头 - 记录重要的响应头

文档结构

推荐章节

1. 简介

   • API 的功能
   • Base URL
   • API 版本
   • 支持联系方式

2. 认证

   • 如何认证
   • Token 管理
   • 安全最佳实践

3. 快速开始

   • 入门简单示例
   • 常见用例演练

4. 端点

   • 按资源组织
   • 每个端点的完整详情

5. 数据模型

   • Schema 定义
   • 字段说明
   • 校验规则

6. 错误处理

   • 错误码参考
   • 错误响应格式
   • 故障排查指南

7. 限流

   • 限制与配额
   • 需要检查的 Header
   • 处理限流错误

8. 更新日志

   • API 版本历史
   • 破坏性变更
   • 弃用通知

9. SDK 与工具

   • 官方客户端库
   • Postman 集合
   • OpenAPI 规范

常见陷阱

问题：文档与代码不同步

症状： 示例无法运行、参数错误、端点返回不同数据 解决方案：

• 从代码注释/注解生成文档
• 使用 Swagger/OpenAPI 等工具
• 添加用于校验文档的 API 测试
• 每次 API 变更时同步审查文档

问题：缺少错误文档

症状： 用户不知道如何处理错误，支持工单增多 解决方案：

• 记录每一种可能的错误码
• 提供清晰的错误信息
• 包含故障排查步骤
• 展示示例错误响应

问题：示例无法运行

症状： 用户无法上手，挫败感增加 解决方案：

• 测试每一个代码示例
• 使用真实、可用的端点
• 包含完整示例（而非片段）
• 提供沙箱环境

问题：参数要求不清晰

症状： 用户发送无效请求，出现校验错误 解决方案：

• 清晰标注必填与可选
• 记录数据类型与格式
• 展示校验规则
• 提供示例值

工具与格式

OpenAPI/Swagger

生成交互式文档：

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'

Postman 集合

导出集合以便轻松测试：

{
  "info": {
    "name": "My API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Create User",
      "request": {
        "method": "POST",
        "url": "{{baseUrl}}/api/v1/users"
      }
    }
  ]
}

相关技能

• @doc-coauthoring - 用于协作撰写文档
• @copywriting - 用于清晰、对用户友好的描述
• @test-driven-development - 用于确保 API 行为与文档一致
• @systematic-debugging - 用于排查 API 问题

其他资源

• OpenAPI Specification
• REST API Best Practices
• GraphQL Documentation
• API Design Patterns
• Postman Documentation

---

专业提示： 让 API 文档尽可能贴近代码。使用可从代码注释生成文档的工具，以确保它们保持同步！