oasdiff — OpenAPI Breaking-Change Diff CLI

简介

oasdiff 可对比两份 OpenAPI 规范并标记破坏性变更，配合 CI 的退出码做门禁；让 API 重构、版本升级与客户端生成更可控，并把风险前置到评审阶段，避免上线后爆雷与回滚，更稳。

• 适合谁： 有 OpenAPI 规范的 API 团队，以及想在 CI 里做契约安全门禁的平台团队
• 可搭配： OpenAPI 的 YAML/JSON；本地文件或 URL；适合 CI（用退出码做 gate）
• 准备时间： 5–15 分钟

实战建议

• 用 breaking 做硬门禁；用 changelog 提升评审可读性。
• CI 建议：把上一版 spec 存成 artifact，在 PR 上做对比。

CI 门禁：阻止不兼容 API 变更

最常见的事故是“字段改名/删除了，但没人发现”。 把它变成强制流程：每个 PR 都对比 base 与 revision：

oasdiff breaking openapi.base.yaml openapi.pr.yaml

只要存在破坏性变更，就会返回非 0 退出码，非常适合做 CI gate。

评审体验：附上可读的变更说明

除了 fail CI，也建议输出人类可读摘要：

oasdiff changelog openapi.base.yaml openapi.pr.yaml > oasdiff.changelog.txt

把关键段落贴进 PR 描述（或让机器人发评论）。

实战建议

• 先统一规范生成方式（bundle/flatten 策略一致）以减少“假 diff”。
• 尽量把 spec 放在仓库里，保证 agent/CI 对比可复现。
• 如果 spec 来自 codegen，固定生成器版本并对比生成结果。

FAQ

它只检测破坏性变更吗？ 答：不只。也支持完整 diff 和 changelog；breaking 是用来做门禁的严格子集。

可以对比 URL 吗？ 答：可以；但 CI 建议使用稳定输入，保证结果可复现。

如何减少噪音？ 答：确保两份 spec 的归一化策略一致（flatten/order/bundle）。