api-documentation-generator

Name: api-documentation-generator
Author: sickn33

github.com/sickn33开发48.7k2.2k 次安装今天更新

代码仓库

关于 api-documentation-generator

为 REST、GraphQL 和 WebSocket API 生成文档的技能，适用于维护 API 文档及帮助开发者和外部用户了解接口。它从代码结构出发整理端点、请求响应和使用说明，并强调核实内容、标注推断与校验 OpenAPI 片段。

主要功能

01分析路由、参数与响应结构
02编写端点与认证说明
03整理错误处理和使用指南
04生成代码示例及 OpenAPI 规范
05校验文档与源代码的一致性

适用场景

01为新 API 编写文档
02随 API 变更更新现有文档
03为外部用户准备接口指南
04创建并校验 OpenAPI 规范

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sickn33/agentic-awesome-skills --skill api-documentation-generator

安装后在 Claude Code 中输入/api-documentation-generator确认已加载。

详细介绍

API 文档生成器

概述

根据代码库自动生成清晰、全面的 API 文档。此技能可帮助你创建专业文档，涵盖端点说明、请求/响应示例、身份验证详情、错误处理和使用指南。

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

何时使用此技能

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

工作原理

步骤 1：分析 API 结构

将文档绑定到实际的源代码修订版、路由/中间件/架构和经过验证的示例。标记缺失或推断出的行为；不要杜撰速率限制、密码策略、令牌过期时间或详尽的错误覆盖范围。使用合成数据和机密占位符。公共用户创建接口不得接受客户端任意提供的管理员角色：除非由经过单独授权的管理员端点验证该权限，否则应省略此项。生成的 OpenAPI 片段必须包含完整的被引用架构/响应，并通过规范验证；交互式“试用”调用属于真实操作，必须使用经批准的沙箱。

首先，我会检查你的 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": "[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"                    // Server-assigned output; do not accept admin from public registration
}
\`\`\`

**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

❌ 不要这样做

不要跳过错误情况 - 用户需要知道可能出现哪些问题
不要使用含糊的描述 - “获取数据”没有帮助
不要忘记身份验证 - 始终记录身份验证要求
不要忽略边缘情况 - 记录分页、筛选和排序
不要留下无法运行的示例 - 测试所有代码示例
不要使用过时的信息 - 让文档与代码保持同步
不要过度复杂化 - 保持简单，便于浏览
不要忘记响应标头 - 记录重要标头

文档结构

建议的章节

简介
- API 的功能
- 基础 URL
- API 版本
- 支持联系方式
身份验证
- 如何进行身份验证
- 令牌管理
- 安全最佳实践
快速入门
- 一个简单的入门示例
- 常见用例演练
端点
- 按资源组织
- 每个端点的完整详情
数据模型
- 架构定义
- 字段说明
- 验证规则
错误处理
- 错误代码参考
- 错误响应格式
- 故障排查指南
速率限制
- 限制和配额
- 需要检查的标头
- 处理速率限制错误
变更日志
- API 版本历史
- 重大变更
- 弃用通知
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"
      }
    }
  ]
}

其他资源

专业提示： 尽可能让 API 文档贴近代码。使用根据代码注释生成文档的工具，确保文档始终与代码保持同步！

限制

仅当任务明确符合上述范围时，才使用此技能。
不要将输出视为环境特定验证、测试或专家审查的替代品。
如果缺少必需的输入、权限、安全边界或成功标准，请暂停并请求澄清。

支持 Markdown

登录后评论

基本信息

作者: sickn33
仓库: sickn33/agentic-awesome-skills
分类: 开发
安装次数: 2,230
GitHub Stars: 48,675

报告问题