跳至主要內容

OpenAPI：先确定契约主源，再选择工具链

高谷深陵大约 3 分钟约 828 字
OpenAPI 契约治理知识海报
OpenAPI 契约主源规范声明、引用闭包、兼容基线和公开边界共同决定契约是否可交付。高清原图

页面能打开，不等于契约正确

同一个文件可能被编辑器接受、被文档 UI 部分渲染，却在 SDK 生成时失败。原因通常不是“某个工具坏了”，而是消费者支持的 OpenAPI 版本、JSON Schema 方言、扩展字段和 $ref 行为不同。根文件必须显式声明规范线：

openapi: 3.1.0
info:
  title: Order API
  version: 1.4.0
servers:
  - url: https://api.example.test
paths:
  /orders/{id}:
    get:
      operationId: getOrder
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: found

规范版本不是越新越好。团队应公布“主源允许的版本”和每个关键消费者的已验证版本；升级先用固定样例验证 lint、bundle、文档、mock、代码生成与网关导入，再改变主源。

拆文件时仍然只有一个主源

大型 API 可以按路径和 schema 拆分，但必须有唯一根入口和可解析的引用闭包：

docs/api/openapi.yaml
docs/api/paths/orders.yaml
docs/api/components/schemas/Order.yaml

本地成功、Linux CI 报引用不存在时，先查执行目录、路径大小写、Git 是否提交目标文件和远程引用授权。bundle 只是把引用收拢为交付物，不证明语义、权限或实现正确。编辑源和生成 bundle 要分目录，禁止人在两个文件上同时修改。

契约是公开面清单

servers、examples、description、extensions、security scheme 与 schema 名称都可能泄漏内网域名、租户、个人信息或未发布能力。公共文档从主源生成前应有显式过滤规则与审查人；示例只用假数据，OAuth client 和 Try it out 指向受控测试入口。

OpenAPI 能声明认证方式，不能证明运行时授权正确。客户端能发出请求，也不能证明网关 CORS、scope 和资源级权限满足设计。验收至少包含一个正向请求、一个无身份拒绝、一个越权拒绝，并关联服务端 trace。

变更以消费者证据为准

合并请求应展示规范 diff、lint 结果、bundle 结果和关键消费者兼容性。删除字段、收紧枚举、改变 required、响应状态或安全要求都可能破坏客户端；只看 YAML 行数无法判断影响。

升级失败时恢复规范声明、规则配置和消费者锁定版本，而不是手改生成文件。远程 $ref、Markdown HTML、自定义扩展与生成模板按供应链输入治理，限制来源并保留版本。每个契约主源都应有 owner、发布目标、弃用期限和删除路径。

官方资料：OpenAPI Specification、OpenAPI Initiative。工具实现分别参见 Swagger 与 Redocly。

跳到正文