OpenAPI 规范基础：版本历史、3.0 与 3.1 区别及文档结构

OpenAPI 规范（原 Swagger 规范）是描述 RESTful API 的行业标准，它定义了一种与语言无关的接口描述格式，使人和机器都能理解 API 的能力。理解其版本演进、核心差异以及文档的基本结构，是进行契约校验的第一步。

2.1 OpenAPI 规范版本历史

OpenAPI 规范经历了从 Swagger 到标准化规范的演进过程，每个主要版本都带来了重要的能力提升。

2.2 OpenAPI 3.0 与 3.1 的核心区别

3.1 版本并非简单的增量更新，而是对规范底层 Schema 语言的一次重大升级。以下表格列出了最关键的差异点：

以下 SVG 图展示了从 OpenAPI 3.0 到 3.1 的核心 Schema 语言升级路径：

2.3 OpenAPI 文档的基本结构

一个标准的 OpenAPI 文档（JSON 或 YAML 格式）由多个顶级对象组成，它们共同描述了 API 的全貌。以下是文档的骨架结构：

openapi: 3.1.0
info:
  title: 示例 API
  version: 1.0.0
  description: 这是一个示例 API 文档
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
security:
  - ApiKeyAuth: []
tags:
  - name: users
    description: 用户相关操作

文档的顶级字段及其职责如下表所示：

以下 SVG 图展示了 OpenAPI 文档的完整结构层次：

2.4 关键结构详解：paths 与 components

paths 和 components 是契约校验中最常被引用的两个顶级对象，理解它们的嵌套关系至关重要。

paths 对象

每个路径下可定义多个操作（HTTP 方法），每个操作包含：

• parameters：路径参数、查询参数、请求头参数
• requestBody：请求体内容及媒体类型
• responses：每个状态码对应的响应结构
• security：操作级别的安全要求（覆盖全局）

components 对象

用于定义可复用的组件，避免重复定义：

• schemas：数据模型定义（最常用）
• parameters：可复用的参数定义
• responses：可复用的响应定义
• requestBodies：可复用的请求体定义
• securitySchemes：认证方案定义（API Key、OAuth2、HTTP Auth）
• headers：可复用的响应头定义
• links：操作间的关联关系
• callbacks：异步回调定义