📚 课程目录第2章 OpenAPI规范基础

2. OpenAPI规范基础：从Swagger到3.x的演进与核心组成

API契约的标准化是架构治理的基石。OpenAPI规范（原Swagger规范）已成为描述RESTful API的事实标准。本章将梳理其发展脉络、核心组成与基础语法，为后续的接口治理实战打下坚实基础。

2.1 发展史：从Swagger到OpenAPI 3.x

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

阶段	版本	时间	核心变化
Swagger诞生	Swagger 1.x	2011	RESTful API描述框架，提供文档生成与客户端SDK工具链
社区普及	Swagger 2.0	2014	成为最广泛使用的API描述格式，支持JSON/YAML，引入`definitions`复用模型
规范捐赠	OpenAPI 2.0	2015	Swagger规范捐赠给Linux基金会，更名为OpenAPI规范，版本号继承
重大重构	OpenAPI 3.0	2017	引入`components`、`oneOf/anyOf`、`requestBody`、`callback`、`server`，废弃`definitions`
稳定迭代	OpenAPI 3.1	2021	完全兼容JSON Schema 2020-12，支持`webhook`、`license`标识符，增强描述能力

迁移建议： 新项目应直接采用OpenAPI 3.0.3或3.1.0。存量Swagger 2.0规范可通过官方转换工具迁移，但需注意definitions到components/schemas的路径变化。

2.2 规范核心组成：三大支柱

一个完整的OpenAPI文档由三个核心顶层字段构成，它们共同定义了API的全貌：

info：元数据层，描述API的标题、版本、描述、联系人、许可证等。
paths：端点层，定义所有可访问的URL路径及其支持的HTTP方法（GET、POST、PUT、DELETE等），包括请求参数、请求体、响应结构。
components：复用层，集中存放可被paths及其他部分引用的模型（schemas）、参数（parameters）、响应（responses）、请求体（requestBodies）、安全方案（securitySchemes）等。

2.3 YAML/JSON基础语法与选择

OpenAPI规范支持YAML和JSON两种序列化格式。YAML因其可读性高、注释支持好，成为编写规范的首选；JSON则更适合程序生成与传输。

2.3.1 格式对比

特性	YAML	JSON
可读性	高，缩进层级清晰，无大量括号	中，大量花括号与引号
注释	支持 `#` 注释	不支持原生注释
数据类型	自动推断，支持多行字符串	严格区分字符串、数字、布尔
引用	支持锚点 `&` 与别名 `*`	仅支持 `$ref`
适用场景	人工编写、代码评审、设计阶段	程序生成、API网关配置、传输

2.3.2 一个完整的OpenAPI 3.0示例（YAML）

以下示例展示了一个用户管理API的规范片段，涵盖了info、paths和components三大核心：

openapi: "3.0.3"
info:
  title: 用户管理API
  version: "1.0.0"
  description: 提供用户注册、查询与删除功能
  contact:
    name: API治理团队
    email: api-governance@example.com

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

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: 用户唯一标识
        name:
          type: string
          description: 用户姓名
        email:
          type: string
          format: email
      required:
        - id
        - name
    CreateUserRequest:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
      required:
        - name
        - email

  关键语法点：
  $ref 引用路径：'#/components/schemas/User' 表示引用当前文档中 components.schemas 下的 User 模型。
requestBody 是OpenAPI 3.x新增字段，替代了Swagger 2.0中 body 参数，更清晰地表达请求体语义。
responses 必须包含至少一个成功状态码（如 "200"），推荐显式定义错误响应。

2.4 从Swagger 2.0到OpenAPI 3.x的关键变化

理解版本差异有助于团队在迁移时避免常见错误：

维度	Swagger 2.0	OpenAPI 3.0+
根对象	`swagger: "2.0"`	`openapi: "3.0.3"`
模型复用	`definitions`	`components/schemas`
请求体	`parameters` 中 `in: body`	独立的 `requestBody` 字段
组合模型	仅 `allOf`	新增 `oneOf`、`anyOf`、`not`
服务器信息	`host` + `basePath` + `schemes`	`servers` 数组，支持多环境与变量
回调	不支持	支持 `callbacks`，用于Webhook场景

常见陷阱： 在OpenAPI 3.x中，servers 字段是一个数组，可以定义多个环境（开发、测试、生产）。如果未定义 servers，默认值为 [{url: "/"}]，这可能导致生成的客户端URL不正确。始终显式定义至少一个 servers 条目。

2.5 小结

本章从Swagger到OpenAPI 3.x的演进历史出发，剖析了规范的核心三支柱——info、paths、components，并通过YAML示例展示了如何编写一个结构清晰的API契约。掌握这些基础，是后续进行API版本管理、兼容性检查与自动化治理的前提。