# oasdiff — OpenAPI Breaking-Change Diff CLI

> oasdiff compares two OpenAPI specs and flags breaking changes with CI-friendly exit codes, so API refactors don’t silently ship incompatible contracts.

## Install

Copy the content below into your project:

## Quick Use

1. Install:
   ```bash
   brew install oasdiff
   # or
   go install github.com/oasdiff/oasdiff@latest
   ```
2. Check breaking changes:
   ```bash
   oasdiff breaking base.yaml revision.yaml
   ```
3. Generate a changelog:
   ```bash
   oasdiff changelog base.yaml revision.yaml
   ```

## Intro

oasdiff compares two OpenAPI specs and flags breaking changes with CI-friendly exit codes, so API refactors don’t silently ship incompatible contracts.

- **Best for:** API teams that publish OpenAPI, and platform teams enforcing contract safety in CI
- **Works with:** OpenAPI YAML/JSON files, local files or URLs, CI pipelines (exit codes)
- **Setup time:** 5–15 minutes

## Practical Notes

- Use `breaking` as a hard gate; use `changelog` to help reviewers.
- CI tip: store previous spec as an artifact and compare on PR.

## CI gate: block incompatible API changes

The common failure mode is “a schema field got renamed and nobody noticed”.
Make it explicit by comparing *base* vs *revision* on every PR:

```bash
oasdiff breaking openapi.base.yaml openapi.pr.yaml
```

If breaking changes exist, the command exits non-zero, which is ideal for CI.

## Reviewer UX: attach a human-friendly changelog

In addition to failing CI, provide a readable summary:

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

Paste the key lines into the PR description (or post via a bot).

## Practical tips

- Normalize specs first (same bundling/flattening strategy) to reduce false diffs.
- Keep specs in-repo so agents and CI can diff deterministically.
- If your spec comes from codegen, pin the generator version and compare the generated output.

### FAQ

**Q: Does it only detect breaking changes?**
A: No. It can also output full diffs and changelogs; `breaking` is the strict subset for gates.

**Q: Can I compare URLs instead of files?**
A: Yes—oasdiff supports various inputs; keep CI inputs stable for deterministic results.

**Q: How do I reduce noisy diffs?**
A: Ensure both specs are normalized the same way (flattening, ordering, bundling).

## Source & Thanks

> Source: https://github.com/oasdiff/oasdiff
> License: Apache-2.0
> GitHub stars: 1,193 · forks: 95

---

<!-- ZH -->

## 快速使用

1. 安装：
   ```bash
   brew install oasdiff
   # 或
   go install github.com/oasdiff/oasdiff@latest
   ```
2. 检测破坏性变更：
   ```bash
   oasdiff breaking base.yaml revision.yaml
   ```
3. 生成变更日志：
   ```bash
   oasdiff changelog base.yaml revision.yaml
   ```

## 简介

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：

```bash
oasdiff breaking openapi.base.yaml openapi.pr.yaml
```

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

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

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

```bash
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）。

## 来源与感谢

> Source: https://github.com/oasdiff/oasdiff
> License: Apache-2.0
> GitHub stars: 1,193 · forks: 95


---
Source: https://tokrepo.com/en/workflows/oasdiff-openapi-breaking-change-diff-cli
Author: Script Depot