oasdiff

oasdiff is a tool for comparing OpenAPI specifications and reviewing API changes. It is best suited to teams that want to catch contract changes before release, whether from a terminal, a pull request, or a browser. Its broad change detection and free core are strong; teams needing formal approvals or longer-lived reviews will need Pro or Enterprise.

Overview

oasdiff compares OpenAPI specifications, creates changelogs, and flags breaking changes before release. It supports OpenAPI 3.0, 3.1, and 3.2, and detects 755 distinct breaking and non-breaking changes. That breadth makes it useful for reviewing routine evolution as well as compatibility risks. It is not a fit for teams whose contracts are in AsyncAPI or GraphQL, neither of which it supports.

The engine, CLI, and GitHub Action are open source under Apache 2.0, and the product also offers a browser diff tool and paid review controls. Self-hosted deployment is supported, giving teams another deployment option alongside its web and platform-specific tools.

Key features

Compare in scripts, pull requests, or a browser

The CLI installs through Homebrew, a shell installer, Docker, or pre-built binaries for Linux, macOS, and Windows. It can emit text, JSON, YAML, HTML, Markdown, or GitHub Actions annotations, so teams can use the same comparison in a script, report, or automated workflow. Composed mode compares collections of OpenAPI files together, which is useful when an API is divided among microservices.

The GitHub Action compares a pull request's specification with the base branch and adds inline annotations for breaking changes. That puts compatibility issues in the review context rather than leaving developers to inspect a separate report. The browser diff tool compares OpenAPI or Swagger specifications without installation or sign-up, and exports text, YAML, JSON, Markdown, or HTML. It is convenient for occasional comparisons, although it does not replace automated pull-request checks for teams that need those checks on every change.

Review privacy and retention

Specifications and changelogs are encrypted client-side before upload; servers retain ciphertext that oasdiff cannot read. Free review links expire after seven days, while Pro reviews remain for the life of the pull request. Enterprise can load specifications directly from GitHub at review time using each reviewer's access, without uploading or storing the specifications. That no-upload mode is a meaningful privacy option for organizations with stricter handling requirements.

AI clients

A hosted MCP server works with Claude, Cursor, and other Streamable HTTP MCP clients. This adds a route for compatible AI clients to use oasdiff, but it does not broaden the underlying contract formats beyond OpenAPI.

Pricing

oasdiff has a free plan, a paid Pro plan, and custom-priced Enterprise. The free tier is unusually capable for teams that mainly need comparisons and pull-request feedback; paid plans are aimed at review governance and organizational support rather than unlocking the basic engine.

• Free — free, free forever. Includes CLI diffing, breaking-change detection and changelogs, GitHub Action inline pull-request annotations, side-by-side review, and encrypted specification storage. No account is required. Its key trade-offs are review links that expire after seven days and the absence of Pro's approval workflow, audit trail, and merge gate.
• Pro — $100 a month, billed $100/month. Adds an approval workflow, audit trail, and merge gate, and covers up to five reviewers across five repositories. This is the appropriate step up for a small team that needs controlled sign-off, but the reviewer and repository caps may constrain broader rollouts.
• Enterprise — custom pricing. Includes unlimited repositories and reviewers, an SLA, dedicated support, and an optional no-upload GitHub mode. It suits organizations that need scale, service commitments, or the stricter GitHub-based privacy path; it is a substantial commitment compared with the free core, and its price depends on the custom arrangement.

A 30-day trial is offered. The free plan is the sensible starting point for individual use or basic team checks; paying makes most sense when review retention or governance controls matter in day-to-day release work.

Platforms

oasdiff supports API workflows and runs on Linux, macOS, and Windows, with web and self-hosted options. The CLI's pre-built binaries cover those desktop and server operating systems, while Docker is another installation route. This range suits teams mixing local development with hosted pull-request review, though contract support remains specifically OpenAPI 3.0, 3.1, and 3.2 in JSON or YAML.

Who it's for

oasdiff is a strong fit for developers and API teams that publish OpenAPI contracts and want repeatable change checks before release. The CLI and open-source GitHub Action suit teams comfortable integrating tooling into development workflows; the browser tool serves reviewers who want a one-off comparison without setup. Teams coordinating approvals across repositories, retaining reviews through a pull request, or enforcing a merge gate have a clearer case for Pro. Enterprises that cannot upload specifications may value Enterprise's optional no-upload GitHub mode. Teams working in GraphQL or AsyncAPI should look elsewhere.

Pros and cons

• Pro: Detects 755 distinct breaking and non-breaking changes across three OpenAPI versions, making review broader than a breaking-only check.
• Pro: Open-source CLI and GitHub Action, plus multiple output formats, support both custom automation and inline pull-request review.
• Pro: The free tier includes core comparisons, changelogs, and pull-request annotations without requiring an account.
• Pro: Client-side encryption and Enterprise's optional no-upload mode give teams distinct privacy choices.
• Con: It does not support AsyncAPI or GraphQL, so teams with those contract types need another tool.
• Con: Free review links last only seven days, and approval, audit, and merge-gating controls require the $100/month Pro plan.
• Con: Pro is limited to five reviewers and five repositories, which may be restrictive for larger teams before Enterprise.

Alternatives

For broader choices, see Contract Testing Tools, API Governance Software, and API Design Tools.

Microcks is a free, fully open-source, community-driven CNCF Incubating project; choose it if that project model and its broader platform range suit your needs better. Pact is free open-source tooling, a reasonable alternative for readers seeking that approach. Specmatic offers free OpenAPI and WSDL contract testing, API resilience testing, and service virtualization, so it is worth considering when testing is the priority. Karate is a free MIT-licensed framework spanning REST, GraphQL, and SOAP API testing as well as browser and desktop UI automation; choose it when that broader testing remit matters more than OpenAPI diffing.

Pact Broker offers a free self-hosted option and PactFlow Starter with unlimited users, two integrations, and bi-directional contract testing, making it an alternative for readers focused on contract coordination. Confluent Cloud has a free Basic tier with managed Kafka clusters and connectors, a different fit for readers seeking managed Kafka resources. Schemathesis is a free open-source tool that generates tests from OpenAPI and GraphQL schemas; choose it when generated schema-based tests are the goal. GraphQL Hive offers a free Hobby plan with one million operations per month and seven-day usage-data retention, an alternative for GraphQL teams.

Verdict

Choose oasdiff if your team uses OpenAPI and wants a capable free comparison engine with a direct path into GitHub pull-request review. Its strongest case is the combination of broad change coverage, open-source automation, and accessible browser comparisons. Look elsewhere if your contracts are GraphQL or AsyncAPI, or if you need approvals and merge controls but cannot justify Pro's $100/month price.