API参考文档创建 api-reference-documentation

---

name: api参考文档创建 description: 使用OpenAPI规范创建专业的API文档，包含端点、认证和交互式示例。适用于记录REST API、创建SDK参考或构建开发者门户。

API参考文档

为开发者集成创建全面的API文档。

OpenAPI 3.0 规范

openapi: 3.0.3
info:
  title: 电子商务API
  version: 1.0.0
  description: 用于管理产品和订单的API
  contact:
    email: api@example.com

servers:
  - url: https://api.example.com/v1
    description: 生产环境
  - url: https://staging-api.example.com/v1
    description: 暂存环境

security:
  - bearerAuth: []

paths:
  /products:
    get:
      summary: 列出产品
      tags: [产品]
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20 }
        - name: category
          in: query
          schema: { type: string }
      responses:
        '200':
          description: 产品列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'

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

  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id: { type: string, format: uuid }
        name: { type: string, maxLength: 200 }
        price: { type: number, minimum: 0 }
        description: { type: string }

文档检查清单

• [ ] 所有端点都记录有示例
• [ ] 认证方法解释清楚
• [ ] 错误响应指定
• [ ] 速率限制文档化
• [ ] 分页解释
• [ ] 网络钩子文档化（如果适用）
• [ ] 多语言SDK示例

最佳实践

• 使用OpenAPI 3.0+规范
• 包含请求/响应示例
• 文档化所有参数和头信息
• 提供认证示例
• 启用交互式API探索
• 维护版本文档
• 包含重大变更的迁移指南

工具

• Swagger Editor / Swagger UI
• Redoc
• Postman Documentation
• Stoplight