4. OpenAPI规范入门

OpenAPI 规范（原 Swagger 规范）是业界最广泛使用的 RESTful API 描述标准。它提供了一种语言无关的、机器可读的接口定义格式，是契约测试、Mock 隔离和集成验证的基石。本章将深入 OpenAPI 3.0 的核心概念，掌握 YAML/JSON 语法，并了解如何自动生成交互式 API 文档。

4.1 OpenAPI 3.0 核心概念

OpenAPI 3.0 文档是一个自包含的 API 描述文件，通常命名为 openapi.yaml 或 openapi.json。其顶层结构由以下几个核心对象组成：

4.2 YAML/JSON 语法基础

OpenAPI 支持 YAML 和 JSON 两种序列化格式。YAML 因其可读性高、注释支持好，成为社区首选。以下是两种格式的对比：

YAML 基础语法示例：

# 这是一个注释
openapi: "3.0.3"
info:
  title: 用户管理 API
  version: "1.0.0"
  description: 用于创建和查询用户信息的接口

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

paths:
  /users:
    get:
      summary: 获取用户列表
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 100
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

4.3 路径与操作定义

paths 对象是 API 的核心。每个路径下可定义多个 HTTP 方法（operation）。每个操作包含以下关键字段：

• operationId：操作的唯一标识符，用于代码生成和日志追踪。
• parameters：路径参数、查询参数、请求头参数。
• requestBody：POST/PUT/PATCH 操作的请求体内容。
• responses：每个 HTTP 状态码对应的响应结构。
• security：该操作的安全要求。

路径参数与查询参数示例：

paths:
  /users/{userId}:
    get:
      summary: 根据 ID 获取用户详情
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: fields
          in: query
          schema:
            type: string
            description: 返回字段列表，逗号分隔
      responses:
        '200':
          description: 用户详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 用户不存在

4.4 组件复用与 Schema 定义

components 是 OpenAPI 3.0 最重要的设计之一。它允许你将数据模型、参数、响应等定义为可复用的组件，通过 $ref 引用。

常见组件类型：

Schema 定义示例：

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          description: 用户唯一标识
        email:
          type: string
          format: email
        name:
          type: string
          maxLength: 100
        role:
          type: string
          enum: [admin, editor, viewer]
          default: viewer
        createdAt:
          type: string
          format: date-time
    PaginatedUsers:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        total:
          type: integer
        page:
          type: integer
        pageSize:
          type: integer

4.5 API 文档自动生成

基于 OpenAPI 规范，可以自动生成多种形式的 API 文档。最常用的工具是 Swagger UI 和 Redoc。

文档生成工具对比：

使用 Swagger UI 的快速启动方式：

# 使用 Docker 运行 Swagger UI
docker run -p 8080:8080 -e SWAGGER_JSON=/app/openapi.yaml -v $(pwd):/app swaggerapi/swagger-ui

# 访问 http://localhost:8080 即可查看交互式文档

4.6 OpenAPI 文档结构总览

下图展示了 OpenAPI 3.0 文档的顶层结构及各部分之间的关系：

4.7 从 OpenAPI 到契约测试

OpenAPI 文档不仅是文档，更是可执行的契约。在微服务架构中，它扮演着以下关键角色：

1. 服务间契约：消费者和提供者基于同一份 OpenAPI 文件进行开发，确保接口一致性。
2. Mock 服务生成：工具如 Prism、WireMock 可直接从 OpenAPI 文件启动 Mock 服务器，返回符合 schema 的示例数据。
3. 契约测试基础：Pact 等框架可以将 OpenAPI 作为契约的起点，验证消费者和提供者的实现是否匹配。
4. API 网关配置：Kong、APISIX 等网关支持导入 OpenAPI 配置，自动生成路由和校验规则。

4.8 本章小结