API文档生成与管理指南：OpenAPI规范、Swagger使用教程与团队协作

api-documentation by supercent-io/skills-template

11,700 周安装量

88 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/supercent-io/skills-template --skill api-documentation

开发技术文档 API

🇨🇳中文介绍

API 文档

何时使用此技能

API 开发：添加新端点时
外部发布：公开 API 上线时
团队协作：定义前后端接口时

使用说明

步骤 1：OpenAPI (Swagger) 规范

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users
  contact:
    email: api@example.com

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

paths:
  /users:
    get:
      summary: List all users
      description: Retrieve a paginated list of users
      tags:
        - Users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create a new user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - email
        - name

    CreateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 2
          maxLength: 50
        password:
          type: string
          minLength: 8
      required:
        - email
        - name
        - password

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer

  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Authentication required"

    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Invalid input"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 2：从代码生成文档 (JSDoc/装饰器)

Express + TypeScript：

/**
 * @swagger
 * /api/users:
 *   post:
 *     summary: Create a new user
 *     tags: [Users]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - email
 *               - name
 *               - password
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *               name:
 *                 type: string
 *               password:
 *                 type: string
 *                 minLength: 8
 *     responses:
 *       201:
 *         description: User created successfully
 *       400:
 *         description: Invalid input
 */
router.post('/users', async (req, res) => {
  const { email, name, password } = req.body;
  const user = await userService.createUser({ email, name, password });
  res.status(201).json(user);
});

步骤 3：交互式文档

Swagger UI 设置：

import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';

const swaggerDocument = YAML.load('./openapi.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: "My API Documentation"
}));

步骤 4：示例与指南

## API 文档

### 认证

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

#### 获取令牌
```bash
curl -X POST https://api.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "..."
}

curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

端点：POST /v1/users

{
  "email": "john@example.com",
  "name": "John Doe",
  "password": "SecurePass123!"
}

成功响应 (201)：

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "john@example.com",
  "name": "John Doe",
  "createdAt": "2025-01-15T10:00:00Z"
}

错误响应 (400)：

{
  "error": "Email already exists"
}

每个 IP 地址每 15 分钟 100 次请求
响应头：X-RateLimit-Remaining

GET /v1/users?page=2&limit=20

响应包含分页信息：

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 157,
    "pages": 8
  }
}

400 - 错误请求（验证错误）
401 - 未授权（缺少/无效令牌）
403 - 禁止访问（权限不足）
404 - 未找到
409 - 冲突（资源重复）
429 - 请求过多（超出速率限制）
500 - 内部服务器错误


## 输出格式

### API 文档结构

docs/ ├── README.md # 概述 ├── getting-started.md # 快速入门指南 ├── authentication.md # 认证指南 ├── api-reference/ │ ├── users.md # 用户相关端点 │ ├── auth.md # 认证相关端点 │ └── products.md # 产品相关端点 ├── guides/ │ ├── pagination.md │ ├── error-handling.md │ └── rate-limiting.md ├── examples/ │ ├── curl.md │ ├── javascript.md │ └── python.md └── openapi.yaml # OpenAPI 规范


## 约束条件

### 必需规则 (MUST)

1.  **真实示例**：提供可运行的代码示例
2.  **错误情况**：不仅要记录成功情况，也要记录失败情况
3.  **保持更新**：当 API 变更时更新文档

### 禁止事项 (MUST NOT)

1.  **示例中使用真实密钥**：不要在示例中使用真实的 API 密钥/密码
2.  **模糊描述**：避免使用像“返回数据”这样不清晰的描述

## 最佳实践

1.  **试用功能**：提供交互式文档 (Swagger UI)
2.  **提供 SDK**：为主要编程语言提供 SDK 和示例
3.  **更新日志**：记录 API 的变更

## 参考资源

*   [OpenAPI 规范](https://swagger.io/specification/)
*   [Swagger UI](https://swagger.io/tools/swagger-ui/)
*   [Redoc](https://redocly.com/)

## 元数据

### 版本信息

*   **当前版本**：1.0.0
*   **最后更新**：2025-01-01
*   **兼容平台**：Claude, ChatGPT, Gemini

### 标签

`#API-documentation` `#OpenAPI` `#Swagger` `#REST` `#developer-docs` `#documentation`

## 示例

### 示例 1：基本用法

### 示例 2：高级用法

每周安装量

11.7K

代码仓库

[supercent-io/sk…template](https://github.com/supercent-io/skills-template "supercent-io/skills-template")

GitHub 星标数

88

首次出现

2026 年 1 月 24 日

安全审计

[Gen Agent Trust HubPass](/supercent-io/skills-template/api-documentation/security/agent-trust-hub)[SocketPass](/supercent-io/skills-template/api-documentation/security/socket)[SnykPass](/supercent-io/skills-template/api-documentation/security/snyk)

安装于

codex11.5K

gemini-cli11.5K

opencode11.5K

github-copilot11.5K

cursor11.5K

amp11.4K

🇺🇸English

API Documentation

When to use this skill

API Development : When adding new endpoints
External Release : Public API launch
Team Collaboration : Frontend-backend interface definition

Instructions

Step 1: OpenAPI (Swagger) Spec

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users
  contact:
    email: api@example.com

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

paths:
  /users:
    get:
      summary: List all users
      description: Retrieve a paginated list of users
      tags:
        - Users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create a new user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - email
        - name

    CreateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 2
          maxLength: 50
        password:
          type: string
          minLength: 8
      required:
        - email
        - name
        - password

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer

  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Authentication required"

    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Invalid input"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

Step 2: Generate Documentation from Code (JSDoc/Decorators)

Express + TypeScript :

/**
 * @swagger
 * /api/users:
 *   post:
 *     summary: Create a new user
 *     tags: [Users]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - email
 *               - name
 *               - password
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *               name:
 *                 type: string
 *               password:
 *                 type: string
 *                 minLength: 8
 *     responses:
 *       201:
 *         description: User created successfully
 *       400:
 *         description: Invalid input
 */
router.post('/users', async (req, res) => {
  const { email, name, password } = req.body;
  const user = await userService.createUser({ email, name, password });
  res.status(201).json(user);
});

Step 3: Interactive Documentation

Swagger UI Setup :

import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';

const swaggerDocument = YAML.load('./openapi.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: "My API Documentation"
}));

Step 4: Examples & Guides

## API Documentation

### Authentication

All API requests require authentication using JWT tokens.

#### Getting a Token
\`\`\`bash
curl -X POST https://api.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'
\`\`\`

Response:
\`\`\`json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "..."
}
\`\`\`

#### Using the Token
\`\`\`bash
curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
\`\`\`

### Creating a User

**Endpoint**: `POST /v1/users`

**Request Body**:
\`\`\`json
{
  "email": "john@example.com",
  "name": "John Doe",
  "password": "SecurePass123!"
}
\`\`\`

**Success Response** (201):
\`\`\`json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "john@example.com",
  "name": "John Doe",
  "createdAt": "2025-01-15T10:00:00Z"
}
\`\`\`

**Error Response** (400):
\`\`\`json
{
  "error": "Email already exists"
}
\`\`\`

### Rate Limiting
- 100 requests per 15 minutes per IP
- Header: `X-RateLimit-Remaining`

### Pagination
\`\`\`
GET /v1/users?page=2&limit=20
\`\`\`

Response includes pagination info:
\`\`\`json
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 157,
    "pages": 8
  }
}
\`\`\`

### Error Codes
- `400` - Bad Request (validation error)
- `401` - Unauthorized (missing/invalid token)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `409` - Conflict (duplicate resource)
- `429` - Too Many Requests (rate limit)
- `500` - Internal Server Error

Output format

API Documentation Structure

docs/
├── README.md                    # Overview
├── getting-started.md           # Quick start guide
├── authentication.md            # Auth guide
├── api-reference/
│   ├── users.md                 # Users endpoints
│   ├── auth.md                  # Auth endpoints
│   └── products.md              # Products endpoints
├── guides/
│   ├── pagination.md
│   ├── error-handling.md
│   └── rate-limiting.md
├── examples/
│   ├── curl.md
│   ├── javascript.md
│   └── python.md
└── openapi.yaml                 # OpenAPI spec

Constraints

Required Rules (MUST)

Real Examples : Provide working code examples
Error Cases : Document not only success but also failure cases
Keep Updated : Update documentation when API changes

Prohibited (MUST NOT)

Real Keys in Examples : Do not use real API keys/passwords in examples
Vague Descriptions : Unclear descriptions like "returns data"

Best practices

Try It Out : Provide interactive documentation (Swagger UI)
Provide SDK : SDK and examples for major languages
Changelog : Document API changes

References

Metadata

Version

Current Version : 1.0.0
Last Updated : 2025-01-01
Compatible Platforms : Claude, ChatGPT, Gemini

Examples

Example 1: Basic usage

Example 2: Advanced usage

Weekly Installs

11.7K

Repository

supercent-io/sk…template

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex11.5K

gemini-cli11.5K

opencode11.5K

github-copilot11.5K

cursor11.5K

amp11.4K

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

144,300 周安装