---

name: api-documentation-generator description: "生成全面、开发者友好的 API 文档，包括端点、参数、示例和最佳实践" risk: unknown source: community date_added: "2026-02-27"

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 路径
• 功能简要描述
• 认证要求
• 速率限制信息（如适用）

请求规范：

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

响应规范：

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

代码示例：

• 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": "user@example.com",      // 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": "user@example.com",
  "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": "user@example.com",
    "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: 'user@example.com',
    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': 'user@example.com',
        '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
  }
}
\`\`\`