4. 契约定义工具：OpenAPI 3.0规范介绍、Swagger Editor使用、YAML/JSON格式选择

API契约的落地离不开标准化的定义工具。本章聚焦三个核心问题：用什么规范描述接口、用什么工具编写与验证、用什么格式存储与维护。OpenAPI 3.0已成为业界事实标准，Swagger Editor提供即时预览与校验能力，YAML与JSON的选择则直接影响团队协作效率。

4.1 OpenAPI 3.0规范核心结构

OpenAPI 3.0（原Swagger规范）是一种与语言无关的RESTful API描述标准。一个完整的OpenAPI文档包含以下顶层对象：

4.2 Swagger Editor：即时契约编写与校验

Swagger Editor是官方提供的在线/本地编辑器，支持实时语法校验、可视化渲染和代码生成。在契约治理流程中，它承担三个关键角色：

1. 编写阶段：左侧编辑YAML/JSON，右侧自动渲染为交互式API文档。
2. 校验阶段：实时检测语法错误、结构缺失、引用断裂等问题。
3. 导出阶段：支持导出为OpenAPI JSON/YAML、生成服务端/客户端代码。

4.3 YAML vs JSON：格式选择策略

OpenAPI 3.0同时支持YAML和JSON两种序列化格式。两者在契约治理场景下的差异如下：

4.4 契约定义最佳实践：以PostgreSQL用户接口为例

以下是一个符合OpenAPI 3.0规范的契约片段，定义了一个用户查询接口，直接映射到PostgreSQL的users表：

openapi: "3.0.3"
info:
  title: 用户数据一致性接口
  version: "1.0.0"
  description: 基于PostgreSQL的CRUD契约，含乐观锁版本控制
paths:
  /users/{userId}:
    get:
      summary: 按ID查询用户
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: 成功返回用户对象
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "404":
          description: 用户不存在
components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - version
      properties:
        id:
          type: integer
          description: 主键，自增
        email:
          type: string
          format: email
        name:
          type: string
        version:
          type: integer
          description: 乐观锁版本号，更新时递增

4.5 工具链集成要点

• 本地开发：使用VS Code + Swagger Viewer插件，实现保存即预览。
• CI校验：在GitHub Actions中集成redocly/openapi-cli，每次PR自动校验契约语法和结构。
• 版本管理：OpenAPI文件与数据库迁移脚本放在同一仓库，使用语义化版本号对齐。
• 格式统一：团队约定使用YAML编写原始契约，CI构建时自动生成JSON副本供网关使用。