📚 课程目录第3章 OpenAPI 3.0规范入门

3. OpenAPI 3.0 规范入门：核心结构、版本选择与格式基础

在支付订单领域聚合建模中，OpenAPI 规范是描述接口契约的行业标准。本章聚焦 OpenAPI 3.0 的核心结构、版本选型策略以及 YAML/JSON 格式的书写要点，为后续的参数配置与测试打下基础。

3.1 OpenAPI 规范的核心结构

一个标准的 OpenAPI 3.0 文档由顶层对象和若干子对象组成，核心结构包含以下 7 个必选或高频使用的部分：

字段	类型	说明
openapi	string	规范版本号，例如 "3.0.3"
info	object	API 元信息：title、version、description
servers	array	服务地址列表，可包含变量替换
paths	object	接口路径与操作（GET/POST/PUT 等）
components	object	可复用的 schemas、parameters、responses 等
security	array	全局安全方案声明
tags	array	接口分组标签，用于文档归类

  关键原则：paths 是文档的核心，每个路径下的 operation 必须包含 operationId、parameters 和 responses。components 用于消除重复定义，提升规范的可维护性。

3.2 版本选择：2.0 vs 3.0 vs 3.1

当前主流版本为 OpenAPI 3.0.x（推荐 3.0.3）。3.1 虽已发布，但工具链支持尚不完善。以下对比帮助你在支付订单项目中做出选择：

特性	Swagger 2.0	OpenAPI 3.0	OpenAPI 3.1
JSON Schema 版本	自定义	JSON Schema Draft 04 扩展	JSON Schema Draft 2020-12
请求体描述	body 参数	requestBody 对象	同 3.0
多态/组合	有限	oneOf / anyOf / allOf	同 3.0 + 增强
示例支持	单示例	多示例（examples）	同 3.0
工具链成熟度	高	高	中
推荐场景	遗留系统	新项目首选	前沿探索

选型建议：支付订单领域建模推荐使用 OpenAPI 3.0.3。它平衡了表达能力与工具生态，主流代码生成器（如 openapi-generator）和测试平台均提供稳定支持。

3.3 YAML / JSON 格式基础

OpenAPI 规范支持 YAML 和 JSON 两种序列化格式。YAML 因可读性高成为首选，JSON 则更适合机器处理。以下是两种格式的对比与书写要点：

维度	YAML	JSON
缩进	空格（2 或 4），禁止 Tab	无严格要求，通常 2 空格
注释	支持 # 注释	不支持注释
字符串引号	大部分情况可省略	必须双引号
多行文本	\| 或 > 块标	需 \n 转义
引用	$ref 与 JSON 相同	$ref 原生支持

以下是一个支付订单查询接口的 YAML 示例片段：

openapi: "3.0.3"
info:
  title: 支付订单聚合 API
  version: "1.0.0"
  description: 用于订单查询、创建与状态同步

paths:
  /orders/{orderId}:
    get:
      operationId: getOrderById
      summary: 根据订单 ID 查询订单详情
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            pattern: '^ORD\d{14}$'
      responses:
        '200':
          description: 成功返回订单对象
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: 订单不存在

常见陷阱：YAML 对缩进敏感，混用 Tab 与空格会导致解析失败。建议在编辑器中开启“显示空白字符”功能，并统一使用 2 空格缩进。

3.4 OpenAPI 3.0 文档结构总览

下图展示了 OpenAPI 3.0 文档的顶层结构及各部分之间的引用关系：

3.5 格式书写规范与工具链

在支付订单项目中，建议遵循以下书写规范：

路径命名：使用小写字母 + 连字符，如 /payment-orders/{orderId}
参数命名：使用 camelCase，如 merchantId、settlementDate
响应状态码：明确区分 2xx（成功）、4xx（客户端错误）、5xx（服务端错误）
示例填充：每个 schema 至少提供一个完整示例，便于测试工具自动生成请求
版本管理：在 info.version 中维护语义化版本，路径中不嵌入版本号

推荐工具：使用 Swagger Editor 进行实时预览与校验，openapi-generator 生成服务端桩代码和客户端 SDK，Redoc 渲染美观的 API 文档页面。

通过掌握 OpenAPI 3.0 的核心结构、版本选型与 YAML/JSON 格式基础，你已具备构建支付订单领域接口规范的能力。下一节将深入讲解如何利用 components 定义可复用的订单模型与参数。