3. OpenAPI 规范版本差异：Swagger 2.0 vs OpenAPI 3.0 vs OpenAPI 3.1

在迁移 OpenAPI 规范时，版本差异是回归冒烟测试的核心关注点。Swagger 2.0、OpenAPI 3.0 和 OpenAPI 3.1 在顶层结构、数据类型系统、安全定义和组件复用机制上存在显著变化。理解这些差异，是编写回归冒烟清单的前提。

3.1 顶层结构差异：info 对象与版本声明

三个版本的 info 对象在必填字段和扩展能力上有所不同，直接影响 API 文档的元数据完整性。

3.2 paths 与操作对象的演进

paths 是 API 路由定义的核心。3.0 引入了 requestBody 替代 2.0 的 body 参数，3.1 则进一步统一了参数描述方式。

• Swagger 2.0： 参数定义在 parameters 列表中，body 参数通过 in: body 和 schema 字段描述。
• OpenAPI 3.0： 引入独立的 requestBody 对象，支持 content 媒体类型映射；parameters 仅用于 query、path、header、cookie。
• OpenAPI 3.1： 保持 3.0 结构，但 schema 字段完全遵循 JSON Schema 2020-12，支持 $defs 和 examples 数组。

# Swagger 2.0 示例
paths:
  /pets:
    post:
      parameters:
        - in: body
          name: pet
          required: true
          schema:
            $ref: '#/definitions/Pet'

# OpenAPI 3.0 / 3.1 示例
paths:
  /pets:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'

3.3 components 与复用机制

components 是 3.0 引入的集中式复用容器，替代了 2.0 分散的 definitions、parameters、responses 顶层字段。

3.4 安全定义：从 securityDefinitions 到 securitySchemes

安全定义是 API 迁移中最容易出错的区域。3.0 将 2.0 的 securityDefinitions 重构为 components/securitySchemes，并增加了 OAuth2 流程的细粒度支持。

3.5 数据类型系统：从 Swagger 子集到 JSON Schema 2020-12

数据类型定义是版本迁移中最深层的变更。3.1 完全采用 JSON Schema 2020-12，带来了更丰富的约束表达能力和 $defs 递归引用。

# OpenAPI 3.1 数据类型示例
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        tag:
          type: [string, null]   # 3.1 方式
      required:
        - id
        - name

3.6 版本差异回归冒烟清单

基于上述差异，以下回归冒烟清单可直接集成到 CI 流水线中，用于验证迁移后的 OpenAPI 规范文件。