OpenAPI 规范基础回顾：3.0/3.1 核心概念

OpenAPI 规范（原 Swagger 规范）是描述 RESTful API 的行业标准接口描述语言。在迁移版本回归测试中，理解规范的核心概念是构建冒烟清单与集成测试的基础。本章聚焦 OpenAPI 3.0 与 3.1 的核心差异及关键元素定义。

3.0 与 3.1 核心差异对比

核心概念结构总览

一个完整的 OpenAPI 文档由以下顶层对象构成，它们共同定义了 API 的契约边界：

• openapi：规范版本号，决定解析器行为。
• info：API 元信息（标题、版本、描述）。
• servers：基础 URL 列表，用于测试环境切换。
• paths：路径与方法的集合，是测试用例的核心来源。
• components：可复用的 schema、参数、响应、请求体。
• tags：路径分组标签，用于测试分类。

路径（Paths）与方法（Methods）

paths 对象是 API 契约的核心，每个路径下可定义多个 HTTP 方法。在回归冒烟清单中，每个路径-方法组合对应一个测试场景。

paths:
  /users/{userId}:
    get:
      summary: 获取用户详情
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回用户对象
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      summary: 更新用户信息
      operationId: updateUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: 更新成功

参数（Parameters）定义

参数分为四种位置类型，每种类型在测试验证时有不同的关注点：

请求体（Request Body）

请求体用于 POST、PUT、PATCH 等方法。OpenAPI 3.x 将请求体从参数中独立出来，支持更精细的内容协商描述。

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - name
          - email
        properties:
          name:
            type: string
            minLength: 1
            maxLength: 100
          email:
            type: string
            format: email
          age:
            type: integer
            minimum: 0
            maximum: 150
    application/xml:
      schema:
        $ref: '#/components/schemas/UserCreate'

响应（Responses）定义

响应定义是回归冒烟清单中断言的核心依据。每个状态码对应一组响应结构，测试需验证状态码、响应头、响应体三个维度。

组件复用（Components）与 Schema

components 对象是 OpenAPI 的复用核心，在迁移测试中，组件变更往往导致连锁影响。以下是最常用的组件类型：

• schemas：数据模型定义，支持组合（allOf/oneOf/anyOf）和引用（$ref）。
• parameters：可复用的参数定义，减少路径中的重复声明。
• responses：通用响应结构，如分页响应、错误响应。
• requestBodies：通用请求体，如批量操作请求。
• headers：可复用的响应头定义。

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - email
    PaginatedResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        total:
          type: integer
        page:
          type: integer
        size:
          type: integer

安全方案（Security）与测试认证

OpenAPI 支持多种安全方案定义，测试框架需根据 security 字段自动注入认证信息：

本章小结

OpenAPI 3.0/3.1 规范为 API 测试提供了完整的契约基础。在迁移版本回归冒烟清单构建中，以下核心概念需要重点掌握：

1. 版本差异：3.1 的 JSON Schema 兼容性带来更精确的类型描述能力。
2. 路径与方法：每个 operationId 对应一个测试场景，路径参数需动态化。
3. 参数与请求体：四种参数位置和请求体内容协商是测试数据构造的依据。
4. 响应定义：状态码、响应头、响应体结构构成断言的三层验证体系。
5. 组件复用：components 的变更会传播到所有引用点，需纳入回归范围。
6. 安全方案：认证信息的自动注入是集成测试自动化的前提条件。