2. OpenAPI 规范基础：发展史、版本对比与核心文件结构

OpenAPI 规范（原 Swagger 规范）是业界描述 RESTful API 的事实标准。理解其演进脉络、版本差异和文件骨架，是实施契约驱动 API 设计治理的第一步。本章从发展史切入，对比 Swagger 2.0、OpenAPI 3.0 和 3.1 的核心变化，并拆解一个标准 OpenAPI 文档的顶层结构。

2.1 发展史：从 Swagger 到 OpenAPI

OpenAPI 规范的演进经历了三个关键阶段：

2.2 版本对比：Swagger 2.0 vs OpenAPI 3.0 vs OpenAPI 3.1

三个版本在核心概念、文件结构、JSON Schema 支持等方面存在显著差异。下表从 API 设计治理视角进行对比：

2.3 核心文件结构

一个标准的 OpenAPI 3.1 文档由以下顶层字段构成。理解这些字段的职责和层级关系，是编写可维护 API 契约的基础。

openapi: "3.1.0"                # 规范版本号
info:                           # API 元信息
  title: 用户管理API
  version: "1.0.0"
  description: 提供用户注册、登录、信息查询等接口
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"
webhooks:                       # Webhook 定义（3.1 新增）
  newUser:
    post:
      summary: 新用户注册通知
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
components:                     # 可复用组件
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    UserList:
      type: array
      items:
        $ref: "#/components/schemas/User"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
security:                       # 全局安全要求
  - bearerAuth: []
tags:                           # 标签分组
  - name: 用户
    description: 用户相关接口
externalDocs:                   # 外部文档
  description: 完整API文档
  url: https://docs.example.com/api

2.4 文件结构关系图

下图展示了 OpenAPI 3.1 文档的顶层字段及其逻辑关系：

2.5 版本选择决策树

在实际项目中，如何选择 OpenAPI 版本？以下决策树可辅助判断：

2.6 实践要点

• 版本声明必须准确： openapi: "3.1.0" 中的版本号必须与规范实际版本一致，否则工具链可能解析失败。
• 优先使用 $ref 复用： 将重复的 schema、参数、响应定义抽取到 components 中，通过 $ref 引用，降低维护成本。
• 路径参数风格统一： 在 OpenAPI 3.x 中，路径参数支持 style 和 explode 属性，建议团队约定统一风格（如 simple + false）。
• 示例驱动设计： 利用 examples 字段提供多场景示例，帮助消费者理解 API 行为。
• 安全方案集中管理： 在 components/securitySchemes 中定义所有安全方案，路径级别通过 security 字段引用。