2. OpenAPI 规范基础：OAS 版本演进与核心结构解析

OpenAPI Specification（OAS）是描述 HTTP API 的标准化接口描述语言，它独立于编程语言、框架和部署环境。理解 OAS 的版本演进和核心结构，是掌握 API 领域边界建模的第一步。本章将系统梳理 OAS 从 Swagger 到 3.1 的演进脉络，并逐层拆解规范文档的骨架与关键字段。

2.1 OAS 版本演进：从 Swagger 到 OpenAPI 3.1

OAS 起源于 2010 年 Swagger 规范，2015 年捐赠给 Linux 基金会后更名为 OpenAPI。下表对比了主要版本的关键差异：

2.2 OAS 核心结构解析：文档骨架

一份标准的 OAS 文档由以下顶级对象构成。我们以 OpenAPI 3.0.3 为例，展示其完整骨架：

openapi: "3.0.3"
info:
  title: 订单服务 API
  version: "1.0.0"
  description: 管理订单的创建、查询与状态变更
servers:
  - url: https://api.example.com/v1
paths:
  /orders:
    get:
      summary: 获取订单列表
      operationId: listOrders
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功返回订单列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
        total:
          type: number
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
security:
  - ApiKeyAuth: []

上述文档的七个顶级字段构成了 OAS 的核心骨架。下表逐一说明其职责：

2.3 路径与操作：API 的行为入口

paths 对象是 OAS 文档的核心，它定义了 API 的所有端点及其支持的 HTTP 方法。每个路径下可包含一个或多个操作对象（operation object），操作对象是描述单个 API 调用的最小单元。

一个完整的操作对象包含以下关键字段：

• operationId：唯一标识操作的字符串，用于工具生成客户端代码和方法名。
• summary / description：操作的简短标题和详细说明。
• parameters：路径参数、查询参数、请求头参数等。
• requestBody：POST/PUT/PATCH 操作的请求体结构（OpenAPI 3.0+）。
• responses：所有可能的 HTTP 状态码对应的响应结构。
• security：覆盖全局安全要求的操作级安全策略。

2.4 Components：复用与解耦的核心

components 对象是 OAS 的复用仓库，它允许将 Schema、参数、响应、请求体、安全方案等定义为可被 $ref 引用的命名对象。这极大地减少了文档冗余，提升了维护性。

components 的常用子对象包括：

2.5 Schema 对象：数据模型的核心

Schema 对象是 OAS 中定义数据结构的核心，它基于 JSON Schema 规范。在 OpenAPI 3.0 中，Schema 对象是 JSON Schema 的子集；在 3.1 中，它完全对齐 JSON Schema 2020-12。

常用的 Schema 关键字包括：

• type：数据类型（string、integer、number、boolean、array、object）。
• properties：对象的属性定义。
• items：数组元素的 Schema。
• required：必填属性列表。
• enum：枚举值列表。
• nullable：是否允许为 null（OpenAPI 3.0 特有；3.1 使用 type: ["string", "null"]）。
• example：示例值。
• description：字段说明。

components:
  schemas:
    Order:
      type: object
      required:
        - id
        - total
        - status
      properties:
        id:
          type: integer
          description: 订单唯一标识
          example: 1001
        total:
          type: number
          format: float
          description: 订单总金额
          example: 299.99
        status:
          type: string
          enum:
            - pending
            - confirmed
            - shipped
            - delivered
          description: 订单状态
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      type: object
      properties:
        productId:
          type: integer
        quantity:
          type: integer
          minimum: 1
        price:
          type: number

2.6 安全方案：保护 API 边界

OAS 支持三种安全方案类型，通过 securitySchemes 定义，在 security 字段中应用：

安全方案可以全局应用，也可以在操作级覆盖：

# 全局安全要求
security:
  - ApiKeyAuth: []
  - BearerAuth: []

# 操作级覆盖（例如公开接口不需要认证）
paths:
  /health:
    get:
      security: []  # 空数组表示无需认证

2.7 本章小结

OAS 规范通过 openapi、info、servers、paths、components、security、tags 七个顶级对象构建了 API 描述的完整骨架。其中 paths 是行为入口，components 是复用中心，Schema 对象是数据模型的核心。掌握这些基础结构，是后续学习 API 领域边界建模、版本管理、代码生成和 API 治理的基石。