OpenAPI 契约

工作原理

OpenAPI 文档描述服务器、路径、操作、参数、请求体、响应和可复用 schema。工具读取文档生成参考文档、类型化客户端、mock 服务器并校验流量。在 CI 中，diff 工具把待发布的 spec 与已发布版本比较，将删除字段、收紧约束或改变类型标记为破坏性变更。

paths:
  /orders/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }

只有被强制执行时，spec 才是契约。设计先行的团队在实现前评审文档；代码先行的团队从注解生成文档，然后再做 lint。

何时使用与取舍

当多个消费者依赖同一个 HTTP API、需要从描述生成 SDK 和网关，或合作伙伴需要无歧义参考时，使用 OpenAPI。它也是契约测试的基础，让生产方与消费方的期望保持一致。

编写和维护完整的 spec 是实际工作量，示例和错误模型常被忽略；生成的 spec 可能格式合法但语义含糊。主要风险是漂移：如果 CI 不比较文档与实现及真实响应，契约就会变成虚构。随 API 一起版本化文档可以避免意外。

示例与误解

团队有时把 200 响应 schema 当作正确性证明。它只说明形状被允许；退款上限等业务规则仍属于代码。应把 spec 与契约测试、边缘运行时校验配合使用。相关概念：契约测试、API 版本管理、API 网关。