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

2. OpenAPI 规范基础：发展史、核心概念与格式选择

在微服务架构中，服务间通信的契约必须精确、可读且可自动化。OpenAPI 规范（原 Swagger 规范）已成为描述 RESTful API 的事实标准。本章将梳理其发展脉络，解析核心概念，并对比 YAML 与 JSON 两种格式的适用场景，为后续任务调度平台的契约设计奠定基础。

2.1 发展史：从 Swagger 到 OpenAPI

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

年份	版本	关键变化
2011	Swagger 1.0	Wordnik 公司内部工具，用于描述 REST API
2014	Swagger 2.0	捐赠给 Linux 基金会，更名为 OpenAPI 规范
2017	OpenAPI 3.0	引入 `components`、`oneOf/anyOf`、回调、链接对象
2021	OpenAPI 3.1	对齐 JSON Schema 2020-12，支持 Webhook、`examples` 增强

版本选择建议： 对于新项目，推荐使用 OpenAPI 3.0.3 或 3.1.0。3.1 提供了更强大的 Schema 表达能力，但工具链支持仍在完善中。任务调度平台建议采用 3.0.3 以保证生态兼容性。

2.2 核心概念详解

OpenAPI 规范的核心由四个概念构成：Path、Operation、Parameter 和 Schema。它们共同定义了 API 的端点、行为、输入与输出。

2.2.1 Path（路径）

Path 是 API 的端点模板，以 / 开头，可包含路径参数（如 /tasks/{taskId}）。每个 Path 下可定义多个 Operation。

2.2.2 Operation（操作）

Operation 对应 HTTP 方法：get、post、put、delete、patch 等。每个 Operation 包含 summary、description、parameters、requestBody 和 responses。

2.2.3 Parameter（参数）

参数分为四种位置：path、query、header、cookie。每个参数需指定 name、in、required 和 schema。

2.2.4 Schema（模式）

Schema 定义数据结构，基于 JSON Schema 标准。用于描述请求体、响应体及参数的类型约束。

  核心关系图： 下图展示了 OpenAPI 文档中 Path、Operation、Parameter 与 Schema 的层级关系。

2.3 核心概念对比表

概念	作用	示例	是否必填
Path	定义 API 端点模板	`/tasks/{taskId}`	是
Operation	定义 HTTP 方法及行为	`get`, `post`	是
Parameter	定义输入参数位置与约束	`in: query, name: status`	按需
Schema	定义数据结构与类型	`type: object, properties: { id: integer }`	按需

2.4 YAML 与 JSON 格式选择

OpenAPI 规范支持 YAML 和 JSON 两种序列化格式。两者在语义上完全等价，但语法和可读性存在差异。

2.4.1 格式对比

维度	YAML	JSON
可读性	高，缩进结构清晰，支持注释	中，括号密集，不支持注释
文件大小	较小（无冗余括号）	较大（键名需双引号）
工具生态	需注意缩进陷阱	解析严格，兼容性最好
适用场景	手写契约、代码评审	机器生成、网络传输

2.4.2 同一契约的两种写法

以下展示一个任务查询接口在 YAML 和 JSON 中的等价表达：

# YAML 版本（推荐手写）
openapi: "3.0.3"
info:
  title: 任务调度平台
  version: "1.0.0"
paths:
  /tasks:
    get:
      summary: 查询任务列表
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [pending, running, completed]
      responses:
        '200':
          description: 成功返回任务列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        status:
          type: string

// JSON 版本（适合机器生成）
{
  "openapi": "3.0.3",
  "info": {
    "title": "任务调度平台",
    "version": "1.0.0"
  },
  "paths": {
    "/tasks": {
      "get": {
        "summary": "查询任务列表",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["pending", "running", "completed"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回任务列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Task"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Task": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "status": { "type": "string" }
        }
      }
    }
  }
}

格式选择建议： 在微服务团队协作中，建议将 YAML 作为源文件格式（便于人工评审和注释），在 CI/CD 流水线中通过工具（如 swagger-cli）转换为 JSON 用于运行时解析。任务调度平台的契约仓库应同时维护两种格式，但以 YAML 为单一事实来源。

2.5 本章小结

OpenAPI 规范从 Swagger 1.0 演进至 3.1，核心能力不断增强。
Path、Operation、Parameter、Schema 构成 API 契约的四大支柱。
YAML 适合手写与评审，JSON 适合机器处理与传输。
任务调度平台推荐使用 OpenAPI 3.0.3 + YAML 源文件 + JSON 运行时。