OpenAPI 规范版本演进与核心语法

在支付订单聚合契约校验体系中，OpenAPI 规范是契约定义的标准语言。理解其版本演进、基础语法与文件结构，是后续编写与校验契约的前提。本节从三个维度展开：版本演进路线、YAML/JSON 语法要点、OpenAPI 文件结构解析。

2.1 OpenAPI 规范版本演进

OpenAPI 规范（原 Swagger 规范）自 2011 年诞生以来，经历了多个重要版本。当前主流版本为 3.0.x 和 3.1.x，2.0 版本仍在部分遗留系统中使用。版本选择直接影响契约校验工具链与表达能力。

2.2 YAML / JSON 基础语法

OpenAPI 文件支持 YAML 和 JSON 两种序列化格式。YAML 因可读性高、注释友好，成为契约编写首选；JSON 常用于程序化生成与传输。以下对比两种格式在支付场景中的写法差异。

YAML 示例：支付订单请求体定义

# 支付订单创建请求体
PaymentOrderRequest:
  type: object
  required:
    - orderId
    - amount
    - currency
  properties:
    orderId:
      type: string
      description: "商户订单号，唯一"
      example: "ORD20250321001"
    amount:
      type: number
      format: decimal
      description: "订单金额，单位：元，保留两位小数"
      example: 199.99
    currency:
      type: string
      enum: [CNY, USD, HKD]
      description: "币种"
    description:
      type: string
      maxLength: 256
      description: "订单描述（可选）"

JSON 等价写法：

{
  "PaymentOrderRequest": {
    "type": "object",
    "required": ["orderId", "amount", "currency"],
    "properties": {
      "orderId": {
        "type": "string",
        "description": "商户订单号，唯一",
        "example": "ORD20250321001"
      },
      "amount": {
        "type": "number",
        "format": "decimal",
        "description": "订单金额，单位：元，保留两位小数",
        "example": 199.99
      },
      "currency": {
        "type": "string",
        "enum": ["CNY", "USD", "HKD"],
        "description": "币种"
      },
      "description": {
        "type": "string",
        "maxLength": 256,
        "description": "订单描述（可选）"
      }
    }
  }
}

2.3 OpenAPI 文件结构解析

一个标准的 OpenAPI 3.0 文件由顶层字段组成，每个字段承担特定职责。支付订单聚合契约通常包含以下结构层次。

2.4 核心字段详解

以下针对支付订单聚合契约中最常用的顶层字段进行说明，并给出典型配置示例。

2.4.1 info — 契约元信息

info:
  title: "聚合支付订单服务 API"
  description: "提供订单创建、查询、退款、异步通知等接口，支持、支付宝、银联"
  version: "2.1.0"
  contact:
    name: "支付中台团队"
    email: "payment@example.com"

2.4.2 servers — 服务地址

servers:
  - url: https://api.pay.example.com/v2
    description: 生产环境
  - url: https://sandbox.pay.example.com/v2
    description: 沙箱测试环境

2.4.3 paths — 接口路径

每个路径下可定义多个 HTTP 方法（GET、POST、PUT、DELETE 等）。支付订单创建通常使用 POST 方法。

paths:
  /orders/create:
    post:
      summary: "创建支付订单"
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentOrderRequest'
      responses:
        '200':
          description: "订单创建成功"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentOrderResponse'
        '400':
          description: "参数校验失败"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

2.4.4 components — 可复用组件

组件是 OpenAPI 3.0 的核心复用机制，避免在多个路径中重复定义相同模型。支付场景中，schemas、parameters、responses、callbacks 最为常用。

components:
  schemas:
    PaymentOrderRequest:
      type: object
      properties:
        orderId:
          type: string
          pattern: '^ORD\d{14}$'
        amount:
          type: number
          minimum: 0.01
          maximum: 999999.99
        currency:
          type: string
          enum: [CNY, USD, HKD]
    PaymentOrderResponse:
      type: object
      properties:
        tradeNo:
          type: string
        status:
          type: string
          enum: [PENDING, SUCCESS, FAILED]
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  callbacks:
    paymentNotify:
      '{$request.body#/notifyUrl}':
        post:
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    tradeNo:
                      type: string
                    status:
                      type: string
          responses:
            '200':
              description: "通知接收成功"

2.5 文件结构完整性检查清单

编写 OpenAPI 支付契约时，可使用以下清单快速检查文件结构是否完整。

• openapi：版本号必须为 3.0.0 或更高，推荐 3.0.3
• info：必须包含 title 和 version，建议包含 description 和 contact
• servers：至少配置一个 url，生产与沙箱环境分开
• paths：每个接口路径必须包含至少一个操作（operation），每个操作必须有 responses
• components.schemas：所有请求体与响应体模型集中定义，通过 $ref 引用
• components.callbacks：异步通知接口必须在此定义，避免遗漏
• tags：可选，但建议按业务模块分组（如订单、退款、对账）