⚡

API参考文档 api-reference-documentation

创建全面的API参考文档，包括OpenAPI/Swagger规范、REST端点、认证、示例和SDK。适用于REST API、GraphQL API文档、端点文档或OpenAPI规范文档化。

后端开发 0 次安装 0 次浏览 更新于 3/3/2026

API参考文档

概览

生成专业的API文档，供开发者集成您的API，包括端点规范、认证、请求/响应示例和交互式文档。

何时使用

  • 文档化REST API
  • 创建OpenAPI/Swagger规范
  • GraphQL API文档
  • SDK和客户端库文档
  • API认证指南
  • 速率限制文档
  • Webhook文档
  • API版本控制指南

OpenAPI规范示例

openapi: 3.0.3
info:
  title: 电子商务API
  description: |
    完整的API用于管理电子商务操作，包括产品、
    订单、客户和支付。

    ## 认证
    所有端点都需要Bearer令牌认证。在Authorization头中包含您的API密钥：`Authorization: Bearer YOUR_API_KEY`

    ## 速率限制
    - 经过身份验证的用户每小时1000个请求
    - 未认证请求每小时100个请求

    ## 分页
    列表端点返回带有`page`和`limit`参数的分页结果。
  version: 2.0.0
  contact:
    name: API支持
    email: api@example.com
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v2
    description: 生产服务器
  - url: https://staging-api.example.com/v2
    description: 暂存服务器
  - url: http://localhost:3000/v2
    description: 本地开发

tags:
  - name: 产品
    description: 产品管理操作
  - name: 订单
    description: 订单处理和跟踪
  - name: 客户
    description: 客户管理
  - name: 认证
    description: 认证端点

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 从/auth/login端点获取的JWT令牌

    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 服务器到服务器认证的API密钥

  schemas:
    产品:
      type: object
      required:
        - 名称
        - 价格
        - SKU
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: "550e8400-e29b-41d4-a716-446655440000"
        名称:
          type: string
          minLength: 1
          maxLength: 200
          example: "无线耳机"
        描述:
          type: string
          maxLength: 2000
          example: "高级降噪无线耳机"
        价格:
          type: number
          format: float
          minimum: 0
          example: 299.99
        SKU:
          type: string
          pattern: '^[A-Z0-9-]+$'
          example: "WH-1000XM5"
        类别:
          type: string
          enum: [electronics, clothing, books, home, sports]
          example: "electronics"
        库存:
          type: integer
          minimum: 0
          example: 150
        图片:
          type: array
          items:
            type: string
            format: uri
          example:
            - "https://cdn.example.com/products/wh-1000xm5-1.jpg"
            - "https://cdn.example.com/products/wh-1000xm5-2.jpg"
        标签:
          type: array
          items:
            type: string
          example: ["无线", "蓝牙", "降噪"]
        创建于:
          type: string
          format: date-time
          readOnly: true
        更新于:
          type: string
          format: date-time
          readOnly: true

    订单:
      type: object
      required:
        - 客户ID
        - 项目
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        客户ID:
          type: string
          format: uuid
        项目:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/订单项'
        状态:
          type: string
          enum: [pending, processing, shipped, delivered, cancelled]
          default: pending
        总金额:
          type: number
          format: float
          readOnly: true
        送货地址:
          $ref: '#/components/schemas/地址'
        创建于:
          type: string
          format: date-time
          readOnly: true

    订单项:
      type: object
      required:
        - 产品ID
        - 数量
      properties:
        产品ID:
          type: string
          format: uuid
        数量:
          type: integer
          minimum: 1
        价格:
          type: number
          format: float
          readOnly: true

    地址:
      type: object
      required:
        - 街道
        - 城市
        - 国家
        - 邮政编码
      properties:
        街道:
          type: string
        城市:
          type: string
        州:
          type: string
        国家:
          type: string
        邮政编码:
          type: string

    错误:
      type: object
      properties:
        代码:
          type: string
        消息:
          type: string
        详细信息:
          type: object

    分页产品:
      type: object
      properties:
        数据:
          type: array
          items:
            $ref: '#/components/schemas/产品'
        分页:
          type: object
          properties:
            页面:
              type: integer
            限制:
              type: integer
            总数:
              type: integer
            总页数:
              type: integer

  responses:
    未授权:
      description: 需要认证
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/错误'
          example:
            代码: "UNAUTHORIZED"
            消息: "认证令牌缺失或无效"

    未找到:
      description: 资源未找到
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/错误'
          example:
            代码: "NOT_FOUND"
            消息: "请求的资源未找到"

paths:
  /products:
    get:
      summary: 列出产品
      description: 使用可选过滤检索分页产品列表
      tags:
        - 产品
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: category
          in: query
          schema:
            type: string
        - name: search
          in: query
          schema:
            type: string
        - name: minPrice
          in: query
          schema:
            type: number
        - name: maxPrice
          in: query
          schema:
            type: number
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/分页产品'
        '401':
          $ref: '#/components/responses/未授权'

    post:
      summary: 创建产品
      description: 创建新产品
      tags:
        - 产品
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/产品'
            examples:
              耳机:
                summary: 无线耳机
                value:
                  名称: "无线耳机"
                  描述: "高级降噪"
                  价格: 299.99
                  SKU: "WH-1000XM5"
                  类别: "electronics"
                  库存: 150
      responses:
        '201':
          description: 创建产品
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/产品'
        '401':
          $ref: '#/components/responses/未授权'

  /products/{productId}:
    get:
      summary: 获取产品
      description: 通过ID检索特定产品
      tags:
        - 产品
      security:
        - bearerAuth: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 找到产品
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/产品'
        '404':
          $ref: '#/components/responses/未找到'

Markdown文档模板

# 产品API

## 概览

产品API允许您管理产品目录，包括创建、
更新、检索和删除产品。

## 基础URL

https://api.example.com/v2


## 认证

所有API请求都需要使用Bearer令牌进行认证：

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/v2/products

端点

列出产品

检索分页产品列表。

端点： GET /products

查询参数：

参数 类型 必需 描述
page number No 页码（默认：1）
limit number No 每页项目数（默认：20）
category string No 按类别过滤
search string No 在名称/描述中搜索

示例请求：

curl -X GET "https://api.example.com/v2/products?page=1&limit=20&category=electronics" \
  -H "Authorization: Bearer YOUR_API_KEY"

示例响应：

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "无线耳机",
      "description": "高级降噪无线耳机",
      "price": 299.99,
      "sku": "WH-1000XM5",
      "category": "electronics",
      "stock": 150,
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

错误响应：

状态码 描述
400 无效参数
401 未授权
500 内部服务器错误 

## 最佳实践

### ✅ 做
- 使用OpenAPI 3.0+规范
- 为每个端点包含请求/响应示例
- 文档化所有查询参数和头信息
- 提供认证示例
- 包含错误响应格式
- 文档化速率限制和分页
- 使用一致的命名约定
- 包含多种语言的SDK示例
- 文档化Webhook有效载荷
- 提供交互式API浏览器（Swagger UI）
- 版本化您的API文档
- 包含破坏性变更的迁移指南

### ❌ 不做
- 跳过错误响应文档
- 忘记文档认证
- 使用不一致的术语
- 留下未文档化的端点
- 忽略弃用通知
- 跳过版本控制信息

## 资源

- [OpenAPI规范](https://swagger.io/specification/)
- [Swagger编辑器](https://editor.swagger.io/)
- [Redoc](https://github.com/Redocly/redoc)
- [Postman文档](https://www.postman.com/api-documentation-tool/)