name: api-documentation-generator description: “从代码中生成全面、开发者友好的 API 文档，包括端点、参数、示例和最佳实践”

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 端点文档

## 创建用户

创建新用户账户。

**端点：** `POST /api/v1/users`

**身份验证：** 必需（Bearer 令牌）

**请求正文：**
\`\`\`json
{
  "email": "user@example.com",      // 必需：有效的电子邮件地址
  "password": "SecurePass123!",     // 必需：最少 8 字符，1 大写字母，1 数字
  "name": "John Doe",               // 必需：2-50 字符
  "role": "user"                    // 可选："user" 或 "admin"（默认："user"）
}
\`\`\`

**成功响应（201 已创建）：**
\`\`\`json
{
  "id": "usr_1234567890",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2026-01-20T10:30:00Z",
  "emailVerified": false
}
\`\`\`

**错误响应：**

- `400 错误请求` - 无效输入数据
  \`\`\`json
  {
    "error": "VALIDATION_ERROR",
    "message": "无效的电子邮件格式",
    "field": "email"
  }
  \`\`\`

- `409 冲突` - 电子邮件已存在
  \`\`\`json
  {
    "error": "EMAIL_EXISTS",
    "message": "此电子邮件已存在账户"
  }
  \`\`\`

- `401 未授权` - 缺少或无效的身份验证令牌

**示例请求（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"
  }'
\`\`\`

**示例请求（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);
\`\`\`

**示例请求（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 文档

## 用户查询

通过 ID 获取用户信息。

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

**变量：**
\`\`\`json
{
  "id": "usr_1234567890"
}
\`\`\`

**响应：**
\`\`\`json
{
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user",
      "createdAt": "2026-01-20T10:30:00Z",
      "posts": [
        {
          "id": "post_123",
          "title": "我的第一篇帖子",
          "publishedAt": "2026-01-21T14:00:00Z"
        }
      ]
    }
  }
}
\`\`\`

**错误：**
\`\`\`json
{
  "errors": [
    {
      "message": "用户未找到",
      "extensions": {
        "code": "USER_NOT_FOUND",
        "userId": "usr_1234567890"
      }
    }
  ]
}
\`\`\`

示例 3：身份验证文档

## 身份验证

所有 API 请求都需要使用 Bearer 令牌进行身份验证。

### 获取令牌

**端点：** `POST /api/v1/auth/login`

**请求：**
\`\`\`json
{
  "email": "user@example.com",
  "password": "您的密码"
}
\`\`\`

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

### 使用令牌

在 Authorization 头中包含令牌：

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

### 令牌过期

令牌在 1 小时后过期。使用刷新令牌获取新访问令牌：

**端点：** `POST /api/v1/auth/refresh`

**请求：**
\`\`\`json
{
  "refreshToken": "refresh_token_here"
}
\`\`\`

最佳实践

✅ 这样做

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

❌ 不要这样做

不要跳过错误案例 - 用户需要知道可能出错的地方
不要使用模糊描述 - “获取数据” 没有帮助
不要忘记身份验证 - 始终文档化身份验证要求
不要忽略边缘情况 - 文档化分页、过滤、排序
不要让示例失效 - 测试所有代码示例
不要使用过时信息 - 保持文档与代码同步
不要过度复杂化 - 保持简单和可扫描
不要忘记响应头 - 文档化重要头部

文档结构

常见陷阱

问题：文档失去同步

症状： 示例不工作，参数错误，端点返回不同数据 解决方案：

从代码注释/注解生成文档
使用如 Swagger/OpenAPI 的工具
添加验证文档的 API 测试
每次 API 变更时审查文档

问题：缺少错误文档

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

文档化每个可能的错误码
提供清晰的错误消息
包括故障排除步骤
显示示例错误响应

问题：示例不工作

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

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

问题：参数要求不明确

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

清晰标记必需与可选
文档化数据类型和格式
显示验证规则
提供示例值

工具和格式

OpenAPI/Swagger

生成交互式文档：

openapi: 3.0.0
info:
  title: 我的 API
  version: 1.0.0
paths:
  /users:
    post:
      summary: 创建新用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'

Postman 集合

导出集合以便轻松测试：

{
  "info": {
    "name": "我的 API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "创建用户",
      "request": {
        "method": "POST",
        "url": "{{baseUrl}}/api/v1/users"
      }
    }
  ]
}

额外资源

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

API文档生成器Skill api-documentation-generator