2. OpenAPI规范基础：发展历史、核心结构与格式选择

OpenAPI规范（原Swagger规范）已成为描述RESTful API的事实标准。理解其发展脉络、核心结构以及YAML与JSON的选型策略，是构建企业级API契约治理的基石。本章将系统梳理这些基础知识点，为后续的架构落地实践打下坚实的技术认知。

2.1 OpenAPI规范的发展历史

OpenAPI规范经历了从社区驱动的Swagger到行业标准的演进过程，其关键里程碑如下表所示：

2.2 OpenAPI 3.x核心结构

OpenAPI 3.x文档是一个自描述的JSON或YAML对象，其顶层结构由以下核心字段组成：

• openapi：必填，声明规范版本号，例如 "3.0.3" 或 "3.1.0"。
• info：必填，包含API的标题、版本、描述、联系信息等元数据。
• servers：必填（至少一个），定义API的基础URL，支持变量替换。
• paths：必填，定义所有API端点及其操作（GET、POST等），是文档的核心。
• components：可选，集中管理可复用的Schema、参数、响应、请求体等对象。
• tags：可选，用于对路径进行逻辑分组，便于文档导航。
• externalDocs：可选，指向外部文档的链接。
• webhooks：可选（3.1新增），描述由API提供方发起的回调事件。

以下是一个精简的OpenAPI 3.0.3文档示例，展示了核心结构：

openapi: "3.0.3"
info:
  title: 企业订单服务API
  version: "1.0.0"
  description: 用于订单创建、查询与状态管理的RESTful接口
servers:
  - url: https://api.example.com/v1
    description: 生产环境
paths:
  /orders:
    get:
      summary: 查询订单列表
      operationId: listOrders
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功返回订单列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string
    OrderList:
      type: array
      items:
        $ref: '#/components/schemas/Order'

2.3 YAML与JSON格式选择

OpenAPI规范支持YAML和JSON两种序列化格式。两者在语法、可读性、工具支持等方面存在差异，选择时需结合团队习惯与使用场景。

以下SVG图展示了OpenAPI 3.x文档的顶层结构及其核心字段之间的关系：

2.4 企业实践中的格式选型策略

基于上述对比，我们推荐以下企业级选型策略：

• 契约设计阶段：使用YAML格式。其注释支持和缩进结构便于团队在代码评审中讨论API设计变更。建议在Git仓库中同时维护YAML源文件与自动生成的JSON文件。
• 运行时解析：使用JSON格式。大多数API网关、服务网格和代码生成器对JSON的解析性能更优，且JSON的严格语法能避免YAML缩进错误导致的运行时故障。
• CI/CD流水线：在构建阶段将YAML源文件转换为JSON，并对JSON进行Schema验证。转换工具推荐使用swagger-cli或redocly-cli。
• 团队规范：无论选择哪种格式，都应统一缩进风格（YAML使用2空格，JSON使用2或4空格），并在编辑器配置中启用自动格式化。