What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
To catch breaking API changes before they reach clients, compare the OpenAPI document from the target branch with the proposed document in continuous integration, then apply a team-defined severity policy. If your project has TypeScript clients or generated types, run the TypeScript compiler as a separate check. A contract diff evaluates declared API changes; TypeScript compilation checks client code, and neither alone proves that the running server behaves as specified.
What makes an API change breaking?
A change is breaking when a consumer that followed the old contract may stop working under the new one. An OpenAPI diff compares the declared API surface in a baseline document with the proposed revision. It can flag removals and stricter requirements that may invalidate existing requests or client assumptions.
As an Amazon Associate I earn from qualifying purchases.
For example, if a request property becomes required, a client that omits it under the old contract may be invalid under the new one. A particular server might still supply a fallback, but that runtime behavior does not change what the new contract declares. Gateways, validators, and generated clients can also enforce the contract differently, so treat a diff as a contract-compatibility signal rather than a report of every server’s actual behavior.
Common changes to examine
- Removed paths or operations.
- Newly required request parameters or properties.
- Narrowed accepted types.
- Response changes that invalidate assumptions made by existing clients.
This is a useful starting set, not an exhaustive rule catalogue. Check the current rules for your chosen diff tool and review each finding against the API’s consumers.
#1 Best Overall
Build a reliable comparison into CI
1. Compare the right documents
Store or generate the OpenAPI document as part of the API build, and retain the document from the target branch as the baseline. Confirm that both files describe the intended revisions. A contract diff can compare documents, but it cannot establish that either one matches deployed server behavior.
2. Run a breaking-change check
oasdiff is one example of a CLI for comparing OpenAPI documents. Its documented command form is oasdiff breaking [flags] base.yaml revision.yaml. To fail on findings classified as definite breaks, the documentation gives this pattern:
oasdiff breaking --fail-on ERR base.yaml revision.yamlThe tool classifies findings as ERR for definite breaking changes, WARN for potential breaks that cannot be confirmed programmatically, and INFO for non-breaking changes. The breaking command reports ERR and WARN checks. With --fail-on WARN, both ERR and WARN findings fail the build; with --fail-on ERR, the gate is limited to ERR findings. Check the current CLI documentation for exact flags and behavior before configuring CI.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →3. Make findings visible in pull requests
The oasdiff GitHub Action documentation describes comparing the pull-request specification with the base-branch specification and adding inline GitHub annotations. Its side-by-side review is enabled by default; the documented review: false input disables that feature. Verify current action inputs and behavior when setting up a workflow, since these can change.
4. Decide what should block a merge
Do not treat every reported item identically. A clear break may call for a fix or a planned compatibility transition; an uncertain warning may need human review; an informational change may not warrant blocking the pull request. Choose the failure threshold that matches your compatibility policy and consumers. If the team approves an exception, record the rationale so future reviewers understand why the contract change was accepted.
Use TypeScript as a complementary client check
TypeScript checks whether code is compatible with the types it sees. Its handbook describes the system as structural subtyping: types are related through their members. If your project maintains TypeScript clients or generates types from its API definition, update or generate those types and run the project’s normal compiler checks. Compilation errors can reveal client code that no longer fits the types it consumes.
That check has a narrower scope than API compatibility. TypeScript does not prove that the server implements the OpenAPI contract, that the OpenAPI file reflects deployed behavior, or that consumers written in other languages remain compatible. Its compatibility rules also include documented unsound allowances, including function-parameter bivariance in certain comparisons. Treat a clean compile as useful evidence about TypeScript client code, not as a runtime compatibility guarantee or replacement for the contract diff.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose and configure a diff tool deliberately
oasdiff offers breaking for changes that may break existing clients, changelog for consumer-affecting changes, and diff for a full definition comparison. Its documentation describes local and CI use and human-readable and machine-readable output. It is one option, not the only suitable tool.
When evaluating a tool for your stack, compare:
- Supported OpenAPI versions and dialect features.
- Coverage and explainability of breaking-change rules.
- How uncertain findings are classified and whether severity is configurable.
- CI integrations, output formats, and build-failure behavior.
- Whether specifications can be handled in your required local or private environment.
- Maintenance and release activity.
The OpenAPI specification page lists versions through 3.2.1, as well as 3.2.0, 3.1.x, 3.0.x, and 2.0. That list is not a guarantee that a particular diff tool supports every version or feature. Confirm support for the versions and constructs your documents actually use in the OpenAPI specification and the tool’s current documentation. The available sources do not establish a complete cross-tool feature matrix.
Investigate contract drift separately
A diff can tell you how two declarations differ; it cannot prove either declaration matches the service that is deployed. If implementation-specific behavior or contract drift is a concern, validate actual server behavior separately using the checks appropriate to your stack. There is no single runtime test strategy that applies to every API.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
