OpenAPI 开发接口指南

什么是 OpenAPI？

OpenAPI（原 Swagger）是一种用于描述 RESTful API 的开放规范。 它允许你以 YAML 或 JSON 格式定义 API 的结构，包括路径、参数、请求/响应格式等。 基于该规范，可以自动生成交互式文档、客户端 SDK、服务端桩代码，甚至进行自动化测试。

核心优势

• 自文档化：API 变更时文档自动同步更新。
• 工具生态丰富：支持 Swagger UI、Redoc、Postman、OpenAPI Generator 等。
• 提升协作效率：前端、后端、测试团队基于同一份契约开发。
• 标准化设计：强制遵循 REST 最佳实践，提高 API 质量。

基础结构示例

以下是一个简单的 OpenAPI 3.0 规范片段：

openapi: 3.0.3
info:
  title: 用户管理 API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回用户数组
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
      required: [id, name]

常用工具推荐

• Swagger UI：将 OpenAPI 文档渲染为交互式网页。
• ReDoc：美观、响应式的 API 文档生成器。
• OpenAPI Generator：根据规范自动生成多种语言的客户端/服务端代码。
• Swagger Editor：在线编辑并实时预览 OpenAPI 文档。

最佳实践建议

1. 使用语义化版本控制（如 v1, v2）管理 API 生命周期。
2. 为所有端点提供清晰的 summary 和 description。
3. 统一错误响应格式，例如包含 code、message 字段。
4. 利用 components 复用模型和参数，避免重复定义。
5. 在 CI/CD 流程中集成 OpenAPI 验证，确保规范与实现一致。

开始你的第一个 OpenAPI 项目

npm install -g @apidevtools/swagger-cli

npx swagger-ui-dist