API 文档生成器

api-documentation-generator

分类编程

作者Agentic Awesome Skills 社区

许可MIT

评分4.70/5

使用10.9K

API 文档生成器

概述

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

适用于 REST API、GraphQL API 和 WebSocket API。

何时使用此技能

需要为新 API 编写文档时

更新现有 API 文档时

API 缺乏清晰文档时

为新加入的开发者提供 API 入门引导时

为外部用户准备 API 文档时

创建 OpenAPI/Swagger 规范时

工作原理

第一步：分析 API 结构

首先，我将检查您的 API 代码库以了解：

可用的端点和路由

HTTP 方法（GET, POST, PUT, DELETE 等）

请求参数和正文结构

响应格式和状态码

身份验证和授权要求

错误处理模式

第二步：生成端点文档

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

端点详情：

HTTP 方法和 URL 路径

功能简述

身份验证要求

速率限制信息（如果适用）

请求规范：

路径参数

查询参数

请求头

请求正文 Schema（包含类型和验证规则）

响应规范：

成功响应（状态码 + 正文结构）

错误响应（所有可能的错误码）

响应头

代码示例：

cURL 命令

JavaScript/TypeScript (fetch/axios)

Python (requests)

根据需要提供其他语言

第三步：添加使用指南

我将包含：

快速入门指南

身份验证设置

常见用例

最佳实践

速率限制详情

分页模式

过滤和排序选项

第四步：记录错误处理

清晰的错误文档，包括：

所有可能的错误码

错误消息格式

故障排除指南

常见错误场景及解决方案

第五步：创建交互式示例

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

Postman 集合

OpenAPI/Swagger 规范

交互式代码示例

示例响应

示例

示例 1：REST API 端点文档

markdown

## 创建用户
创建一个新的用户账户。
端点： POST /api/v1/users
身份验证： 必需 (Bearer token)
请求正文：
\\\json
{
  "email": "[email protected]",      // 必需：有效的电子邮件地址
  "password": "SecurePass123!",     // 必需：最少 8 位，含 1 个大写字母和 1 个数字
  "name": "John Doe",               // 必需：2-50 个字符
  "role": "user"                    // 可选："user" 或 "admin" (默认: "user")
}
\\\
成功响应 (201 Created)：
\\\json
{
  "id": "usr_1234567890",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2026-01-20T10:30:00Z",
  "emailVerified": false
}
\\\
错误响应：
400 Bad Request - 输入数据无效
  \\\json
  {
    "error": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "field": "email"
  }
  \\\
409 Conflict - 电子邮件已存在

json

{
    "error": "EMAIL_EXISTS",
    "message": "An account with this email already exists"
  }

401 Unauthorized - 缺少或无效的身份验证令牌

请求示例 (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"
  }'

请求示例 (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);

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

markdown

## 用户查询通过 ID 获取用户信息。

Query:

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

code

Variables:

json
{
"id": "usr_1234567890"
}

code

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"
}
]
}
}
}

code

Errors:

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

code

示例 3：身份验证文档

markdown

## 身份验证所有 API 请求都需要使用 Bearer 令牌进行身份验证。获取令牌端点: POST /api/v1/auth/login

请求:

json
{
"email": "[email protected]",
"password": "your-password"
}

code

响应:

json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600,
"refreshToken": "refresh_token_here"
}

code

### 使用令牌

在 Authorization 请求头中包含该令牌：

Authorization: Bearer YOUR_TOKEN

code

### 令牌过期令牌在 1 小时后过期。请使用刷新令牌获取新的访问令牌：端点: POST /api/v1/auth/refresh

请求:

json
{
"refreshToken": "refresh_token_here"
}

code

最佳实践

✅ 推荐做法

保持一致性 - 所有端点使用相同的格式

包含示例 - 提供多种语言的可运行代码示例

记录错误 - 列出所有可能的错误代码及其含义

展示真实数据 - 使用真实的示例数据，而非 "foo" 和 "bar"

解释参数 - 描述每个参数的作用及其约束条件

API 版本化 - 在 URL 中包含版本号 (/api/v1/)

添加时间戳

时间戳 - 显示文档最后更新时间

关联相关端点 - 帮助用户发现相关功能

包含速率限制 - 记录所有速率限制策略

提供 Postman 集合 - 方便用户测试 API

❌ 避免这样做

不要忽略错误情况 - 用户需要知道可能出现的问题

不要使用模糊的描述 - “获取数据”这类描述没有帮助

不要忘记身份验证 - 始终记录认证要求

不要忽略边缘情况 - 记录分页、过滤和排序

不要让示例失效 - 测试所有代码示例

不要使用过时信息 - 保持文档与代码同步

不要过度复杂化 - 保持简洁且易于扫描

不要忘记响应头 - 记录重要的 Header

文档结构

常见陷阱

问题：文档与代码不同步

症状： 示例无法运行，参数错误，端点返回的数据与描述不符 解决方案：

通过代码注释/注解自动生成文档

使用 Swagger/OpenAPI 等工具

添加验证文档准确性的 API 测试

每次 API 变更时同步审查文档

问题：缺失错误文档

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

记录所有可能的错误代码

提供清晰的错误消息

包含故障排除步骤

展示错误响应示例

问题：示例无法运行

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

测试每一个代码示例

使用真实可用的端点

提供完整的示例（而非片段）

提供沙箱环境

问题：参数要求不明确

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

明确标注“必填”与“可选”

记录数据类型和格式

展示校验规则

提供示例值

工具与格式

OpenAPI/Swagger

生成交互式文档：

yaml

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 Collection

导出集合以便快速测试：

json

{
  "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"
      }
    }
  ]
}

code

## 相关技能
@doc-coauthoring - 用于协作编写文档
@copywriting - 用于编写清晰、用户友好的描述
@test-driven-development - 用于确保 API 行为与文档一致
@systematic-debugging - 用于排查 API 问题
附加资源
OpenAPI 规范
REST API 最佳实践
GraphQL 文档
API 设计模式
Postman 文档
---
专业提示： 尽量让 API 文档与代码保持同步。建议使用能从代码注释生成文档的工具，以确保两者一致！
局限性
仅在任务明确符合上述范围时使用此技能。
不要将输出结果视为环境特定验证、测试或专家评审的替代方案。
如果缺少必要的输入、权限、安全边界或验收标准，请停止操作并请求澄清。

API 文档生成器

API 文档生成器

概述

何时使用此技能

工作原理

第一步：分析 API 结构

第二步：生成端点文档

第三步：添加使用指南

第四步：记录错误处理

第五步：创建交互式示例

示例

示例 1：REST API 端点文档

示例 2：GraphQL API 文档

示例 3：身份验证文档

获取令牌

最佳实践

✅ 推荐做法

❌ 避免这样做

文档结构

推荐章节

常见陷阱

问题：文档与代码不同步

问题：缺失错误文档

问题：示例无法运行

问题：参数要求不明确

工具与格式

OpenAPI/Swagger

Postman Collection

附加资源

局限性

扫码进交流群