
关于
从代码生成全面、开发者友好的 API 文档,包括端点、参数、示例和最佳实践
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
}
}
\`\`\`
兼容工具
Claude CodeCursor
标签
后端开发
