2. OpenAPI 规范入门：OpenAPI 3.0 核心概念、YAML/JSON 定义、路径与操作、请求/响应模型

OpenAPI 规范（原 Swagger 规范）是描述 RESTful API 的行业标准。OpenAPI 3.0 作为当前主流版本，提供了结构化的接口定义语言，使契约测试、性能调优和故障排查有了统一的契约基础。本节将系统梳理其核心概念与表达方式。

2.1 OpenAPI 3.0 核心概念

OpenAPI 3.0 文档是一个自描述的 API 契约，包含以下核心顶层对象：

2.2 YAML / JSON 定义方式

OpenAPI 3.0 支持 YAML 和 JSON 两种序列化格式。YAML 因其可读性高、注释友好，成为社区首选；JSON 则更适合程序化生成和传输。

格式对比：

YAML 示例（推荐）：

openapi: "3.0.3"
info:
  title: 订单服务 API
  version: "1.0.0"
  description: 提供订单创建与查询能力
servers:
  - url: https://api.example.com/v1
    description: 生产环境
paths:
  /orders:
    get:
      summary: 查询订单列表
      operationId: listOrders
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功返回订单列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
        total:
          type: number
          format: float
    OrderList:
      type: array
      items:
        $ref: '#/components/schemas/Order'

JSON 等价示例：

{
  "openapi": "3.0.3",
  "info": {
    "title": "订单服务 API",
    "version": "1.0.0"
  },
  "paths": {
    "/orders": {
      "get": {
        "operationId": "listOrders",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回订单列表",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrderList" }
              }
            }
          }
        }
      }
    }
  }
}

2.3 路径与操作

paths 对象是 API 的路由映射表。每个路径下可定义多个 HTTP 操作（method），形成完整的端点契约。

路径定义规则：

• 静态路径： /users、/orders，直接匹配固定资源。
• 路径参数： /users/{userId}，使用花括号声明变量，在 parameters 中定义类型。
• 操作对象： 每个路径下可包含 get、post、put、delete、patch 等。

操作对象核心字段：

2.4 请求 / 响应模型

OpenAPI 3.0 使用 requestBody 和 responses 精确描述 API 的输入输出契约。这是契约测试的核心验证对象，也是性能调优时构造压测 payload 的依据。

2.4.1 请求模型

请求模型包含三个维度：

• 参数（parameters）： 路径参数、查询参数、请求头参数。每个参数需定义 name、in（位置）、schema（类型约束）、required（是否必填）。
• 请求体（requestBody）： 用于 POST、PUT、PATCH。需声明 content.type（如 application/json）和对应的 schema。
• 安全方案（security）： 声明操作所需的认证方式（如 Bearer Token、API Key）。

请求参数定义示例：

parameters:
  - name: orderId
    in: path
    required: true
    schema:
      type: integer
      minimum: 1
  - name: pageSize
    in: query
    required: false
    schema:
      type: integer
      default: 20
      maximum: 100
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CreateOrderRequest'

2.4.2 响应模型

响应模型按 HTTP 状态码组织，每个状态码对应一个响应对象：

响应定义示例：

responses:
  '200':
    description: 订单详情
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Order'
  '404':
    description: 订单不存在
    content:
      application/json:
        schema:
          type: object
          properties:
            code:
              type: string
              example: "ORDER_NOT_FOUND"
            message:
              type: string
              example: "未找到指定订单"

2.5 组件复用与 $ref 引用

components 对象是 OpenAPI 3.0 的复用机制，避免在多个路径中重复定义相同的数据结构。契约测试中，组件定义是验证响应体结构的权威来源。

组件分类：

$ref 引用语法：

# 引用 schema 组件
schema:
  $ref: '#/components/schemas/Order'

# 引用参数组件
parameters:
  - $ref: '#/components/parameters/pageToken'

# 引用响应组件
responses:
  '404':
    $ref: '#/components/responses/NotFound'

2.6 契约测试视角的 OpenAPI 最佳实践

1. 显式声明所有响应状态码： 包括 4xx 和 5xx，确保契约测试覆盖异常路径。
2. 使用 example 字段： 为每个 schema 属性提供示例值，便于自动生成测试数据。
3. 定义 nullable 和 required： 明确字段的可空性和必填性，避免测试用例遗漏边界情况。
4. 统一错误响应结构： 在 components/responses 中定义全局错误格式，确保所有接口的错误体一致。
5. 标注 deprecated 操作： 弃用接口在契约中标记，性能压测时自动跳过。