oasdiff

Overview

oasdiff compares OpenAPI specifications, generates changelogs, and identifies breaking changes ahead of release. It supports OpenAPI 3.0, 3.1, and 3.2 and detects 755 distinct breaking and non-breaking changes, making it useful for reviewing routine API evolution as well as compatibility risks. Teams working in AsyncAPI or GraphQL should look elsewhere: neither format is supported.

The engine, CLI, and GitHub Action are open source under Apache 2.0. The product adds a browser-based diff and paid review coordination, with self-hosted deployment also supported.

Key features

Comparisons for scripts, pull requests, and browsers

The CLI installs through Homebrew, a shell installer, Docker, or pre-built Linux, macOS, and Windows binaries. Its output spans text, JSON, YAML, HTML, Markdown, and GitHub Actions annotations, so teams can use results in scripts, reports, or automation. Composed mode compares collections of OpenAPI files together, a useful fit for APIs divided across microservices.

The GitHub Action compares a pull request's specification with the base branch and adds inline annotations for breaking changes. That puts compatibility concerns in the review flow rather than leaving developers to discover them after a merge. The browser diff compares OpenAPI or Swagger specifications without installation or sign-up and exports several of the same formats, making it a low-friction option for occasional reviews.

Privacy and AI access

Specifications and changelogs are encrypted client-side before upload; servers retain ciphertext that oasdiff cannot read. Enterprise can go further by loading specifications directly from GitHub at review time using each reviewer's access, without uploading or storing the specs. A hosted MCP server works with Claude, Cursor, and other Streamable HTTP MCP clients, extending access to AI tools without changing the product's OpenAPI focus.

Pricing

The Free plan costs 0.00 USD per free and is billed Free forever. It includes CLI diffing, breaking-change detection, changelogs, GitHub Action inline PR annotations, side-by-side review, and encrypted spec storage, with no account required. That is a strong starting point for individual developers and teams that can work without formal approvals. Free review links expire after 7 days, however, which limits their usefulness for reviews that need to remain available longer.

Pro costs 100.00 USD per month, billed $100/month. It adds an approval workflow, audit trail, and merge gate, and covers up to 5 reviewers across 5 repositories. This is the relevant step up for teams that need governed sign-off, but the reviewer and repository caps may constrain wider adoption.

Enterprise has custom pricing and includes unlimited repositories and reviewers, an SLA, dedicated support, and the optional no-upload GitHub mode. Enterprise reviews remain available for the life of the pull request. It suits organizations with broader review programs or stricter spec-handling needs; teams should weigh custom pricing against Pro's fixed capacity and the free plan's shorter-lived links.

A 30-day trial is available. The free plan remains free forever, while Pro is billed monthly.

Platforms

oasdiff supports API workflows and Linux, macOS, and Windows, alongside web access and self-hosted deployment. The CLI's installer choices and browser diff give teams distinct ways to adopt it, though the product's contract coverage remains specifically OpenAPI rather than a general API testing suite.

Who it's for

oasdiff is a good choice for developers and API teams that publish OpenAPI contracts and want change detection in local workflows or pull requests. Its broad change coverage, multiple output formats, and open-source engine make it especially practical where teams can build around the CLI or GitHub Action. It is less suitable for teams needing AsyncAPI or GraphQL coverage, or for small groups that require durable review links and approvals but cannot justify Pro.

Pros and cons

• Pros: 755 change types and support for three OpenAPI versions provide broad contract review coverage.
• Pros: The open-source CLI and GitHub Action, plus multiple output formats, support automation without requiring Pro.
• Pros: Client-side encryption protects uploaded specs, while Enterprise's no-upload mode addresses more restrictive handling requirements.
• Cons: AsyncAPI and GraphQL are unsupported, ruling it out for teams using those contract formats.
• Cons: Free review links last only 7 days; longer-lived pull-request reviews and formal controls require paid plans.
• Cons: Pro's $100/month plan covers at most 5 reviewers and 5 repositories, so larger teams need Enterprise.

Alternatives

For broader contract testing choices, compare Contract Testing Tools, or browse API Governance Software and API Design Tools for adjacent needs.

• Microcks is a free, open-source, community-driven CNCF Incubating project; consider it if that project model is a priority.
• Pact offers free open-source tooling; consider it when that tooling is a better fit for your contract workflow.
• Specmatic offers free contract testing and API resilience testing, with OpenAPI, WSDL, and MCP coverage; choose it if those formats or testing capabilities matter more than oasdiff's change review.
• Confluent Cloud has a free Basic tier for managed Kafka clusters and connectors; consider it for that managed streaming use case.
• Karate offers a free framework for REST, GraphQL, and SOAP API testing, plus browser and desktop UI automation; it is a better fit when those test types are the priority.
• Pact Broker offers free options including unlimited users on PactFlow Starter and a self-hosted broker; consider it for Pact-oriented contract workflows.
• Schemathesis is a free open-source tool that generates tests from OpenAPI and GraphQL schemas; pick it when generated API testing is the goal.
• GraphQL Hive has a free Hobby tier with 1M operations per month and 7-day usage-data retention; consider it for GraphQL schema and usage workflows.

Verdict

Choose oasdiff if your team works with OpenAPI and wants broad change detection that can run in a CLI or annotate GitHub pull requests, with a useful free tier. Look elsewhere if your contracts are AsyncAPI or GraphQL, or if you need durable reviews and approvals but cannot meet Pro's $100/month price and team limits.