2. OpenAPI 规范基础：从 Swagger 到 OpenAPI 的演进与核心差异

OpenAPI 规范（原 Swagger 规范）是 RESTful API 描述的事实标准。理解其发展脉络、版本差异及文件结构，是进行 API 设计治理与契约隔离的基石。本章将系统梳理从 Swagger 2.0 到 OpenAPI 3.1 的关键变化，并解析规范文件的基本骨架。

2.1 发展历史：从 Swagger 到 OpenAPI 的标准化之路

OpenAPI 规范经历了从社区工具到国际标准的演进过程，其关键里程碑如下：

2.2 核心版本差异：2.0 vs 3.0 vs 3.1

三个版本在文件结构、数据模型、复用机制等方面存在显著差异。以下从 API 设计治理视角进行对比：

2.3 规范文件的基本结构

OpenAPI 规范文件（JSON 或 YAML 格式）遵循固定的顶层结构。以下以 OpenAPI 3.1 为例，展示其核心骨架：

openapi: "3.1.0"
info:
  title: 用户管理 API
  version: "1.0.0"
  description: 用于用户注册、登录与信息查询的 RESTful 接口

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

paths:
  /users:
    get:
      summary: 获取用户列表
      operationId: listUsers
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"
    post:
      summary: 创建新用户
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "201":
          description: 用户创建成功

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
    UserList:
      type: array
      items:
        $ref: "#/components/schemas/User"
    CreateUserRequest:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
        email:
          type: string
          format: email

webhooks:
  userCreated:
    post:
      summary: 用户创建事件通知
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        "200":
          description: 通知成功

2.4 规范结构可视化：OpenAPI 文件顶层架构

下图展示了 OpenAPI 3.1 规范文件的顶层结构及各部分之间的引用关系：

2.5 版本选择与治理策略

在 API 设计治理中，版本选择直接影响工具链、Mock 生成与契约校验。以下是推荐策略：

• 新项目首选 OpenAPI 3.1：完整 JSON Schema 支持、Webhook 原生定义、更好的类型系统，适合长期治理。
• 存量 2.0 项目逐步迁移：优先迁移核心 API，使用 openapi-converter 工具辅助转换，但需人工审核 requestBody 与 components 的映射。
• 工具链兼容性检查：确保 CI/CD 中的校验器、Mock 服务器、代码生成器均支持所选版本。例如，OpenAPI 3.1 的 JSON Schema 2020-12 特性需要较新的工具版本。
• 契约仓库统一版本：所有 API 契约文件必须声明相同的 openapi 版本，避免混合版本导致解析混乱。