OpenAPI 接口规范

什么是 OpenAPI？

OpenAPI 规范（原 Swagger 规范）是一种用于描述 RESTful API 的标准格式。 它允许人类和机器在不访问源代码或文档的情况下理解服务的功能。 OpenAPI 支持 YAML 或 JSON 格式，广泛用于 API 文档生成、客户端 SDK 自动生成、测试等场景。

当前主流版本为 OpenAPI 3.x，由 OpenAPI Initiative 维护。

核心优势

• ✅ 自动生成交互式文档（如 Swagger UI）
• ✅ 统一接口契约，提升前后端协作效率
• ✅ 支持自动化测试与 Mock 服务
• ✅ 多语言客户端/服务端代码生成（通过工具如 openapi-generator）
• ✅ 提升 API 可发现性与可维护性

基本结构示例

以下是一个简单的 OpenAPI 3.0 规范片段（YAML 格式）：

openapi: 3.0.3
info:
  title: 用户管理 API
  version: 1.0.0
  description: 提供用户注册、查询等基础功能
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
          format: email

常用字段说明

• openapi：规范版本（如 3.0.3）
• info：API 元信息（标题、版本、描述等）
• servers：API 基础 URL 列表
• paths：定义所有端点及其操作（GET/POST 等）
• components：复用组件（如 schemas、parameters、responses）

推荐工具链

• Swagger Editor：在线编辑与预览 OpenAPI 文件
• Swagger UI：将 OpenAPI 文件渲染为交互式文档
• Redoc：另一种美观的 OpenAPI 文档渲染器
• openapi-generator：从规范生成客户端/服务端代码
• Postman：支持导入 OpenAPI 并生成集合

最佳实践建议

1. 始终使用语义化版本号管理 API 版本
2. 为每个操作提供清晰的 summary 和 description
3. 使用 components/schemas 复用数据模型
4. 明确定义错误响应（如 400、401、500）
5. 结合 CI/CD 流程校验 OpenAPI 文件合法性