apidrifter vs oasdiff
oasdiff and apidrifter both compare two OpenAPI documents and classify every change as breaking or not, and apidrifter uses oasdiff's check IDs where the meaning matches, so CI config and habits carry over. oasdiff is the more established spec differ: written in Go, with a catalog of checks you can list and customize, six output formats, a git diff driver, a pre-commit hook, a GitHub Action that annotates pull requests inline, a hosted MCP server, and a paid review and approval workflow at oasdiff.com. apidrifter's differ is one half of a tool whose other half runs the spec against a live server to find where document and implementation disagree, and it covers MCP servers as well as OpenAPI. If spec-to-spec diff is the whole job, oasdiff is the safe choice. If you also need to know whether the server does what the new spec says, use apidrifter for that part.
Feature by feature
| Feature | apidrifter | oasdiff |
|---|---|---|
| Spec vs implementation verification | Yes. plan, run and verify send requests from the spec to a live server and check every response. | No. oasdiff compares documents only. |
| Property-based fuzzing | No. | No. |
| Breaking-change diff between spec versions | Yes. breaking, diff and changelog over 357 polarity-aware rules; exit 1 on breaking changes. | Yes. breaking, changelog, diff and summary; customizable severity levels; deprecation sunset-period checks. |
| MCP server snapshot and diff | Yes. Tools, resources, prompts and instructions, with description changes tracked. | No. |
| Agent-native MCP interface | Yes. apidrifter serve runs locally over stdio; documents stay on your machine. | Yes. A hosted MCP server at api.oasdiff.com/mcp, called from an AI assistant. |
| Which side to fix | Yes. Every verification finding carries a fix for the spec and a fix for the implementation. | Not applicable. There is no implementation in a spec-to-spec comparison. |
| GitHub Action | Yes. Composite action: changelog in the job summary, fail-on threshold, optional PR comment. | Yes. oasdiff/oasdiff-action with breaking, changelog, diff and validate; inline annotations and fail-on. |
| Hosted or paid tiers | None. The CLI is free; a hosted service is planned. | The CLI, the Action and the shareable side-by-side review are free. oasdiff Pro adds the approval workflow and audit trail. |
| Spec formats | OpenAPI 3.x and MCP snapshots. Swagger 2.0 must be converted to OpenAPI 3 first. | OpenAPI 3.0, 3.1 and 3.2, with an upgrade command that canonicalizes 3.0 to 3.x. |
| Other spec tooling | None beyond diff and verification. | validate, flatten, upgrade, breaking-files, a git diff driver, a pre-commit hook, and output localized in en, ru, pt-br and es. |
| Output formats | Text, JSON, Markdown. | html, json, markdown, markup, text and yaml. |
| Language and runtime | TypeScript. Node 22.12 or newer; run with npx. | Go. Prebuilt binaries, Homebrew, Docker, go install, asdf. |
| License | Apache-2.0 | Apache-2.0 |
When to use oasdiff instead
Reach for oasdiff when:
- Spec-to-spec diff is the whole job and your team already runs it.
- You cannot or do not want to run Node in CI; oasdiff ships as a static binary.
- You need the review and approval workflow with commit statuses, or HTML and YAML output.
- You want deprecation sunset periods enforced, the git diff driver, or the pre-commit hook.
Use them together
Keep oasdiff for the comparison it already does and add apidrifter for the comparison it cannot: the new document against the deployed server.
# Spec-to-spec, in the tool your team already runs
oasdiff breaking openapi.before.yaml openapi.yaml
# The same comparison with apidrifter's engine; rule IDs overlap where the meaning matches
npx apidrifter breaking openapi.before.yaml openapi.yaml
# The part oasdiff does not do: the new document against the staging server
npx apidrifter run openapi.yaml --base-url https://staging.example.com --bearer-env API_TOKENDisagreements between the two differs are worth a bug report to whichever tool is wrong; apidrifter keeps an oracle harness in the repository for exactly that.
Frequently asked questions
- Do apidrifter and oasdiff use the same rule IDs?
- Where a rule means the same thing, yes, so severity overrides and ignore lists carry over. apidrifter has rules oasdiff does not and the reverse, so check the rules reference before assuming an ID exists on both sides.
- Should I replace oasdiff with apidrifter in CI?
- Not if oasdiff is working for you. The reason to add apidrifter is apidrifter run, which checks the spec against the live implementation. You can keep oasdiff for the spec diff and add the verification step beside it.
- Which handles OpenAPI 3.1 and 3.2?
- oasdiff documents 3.1 and 3.2 support and ships an upgrade command. apidrifter accepts any OpenAPI 3.x document and treats the parts it understands; Swagger 2.0 must be converted first in both cases.
- Does either have an MCP interface for agents?
- Both. oasdiff offers a hosted MCP server at api.oasdiff.com/mcp. apidrifter serve runs locally over stdio, so specs never leave the machine, and it also exposes plan, run, verify and the MCP snapshot tools.
Sources
Last reviewed . If something here about oasdiff is out of date, open an issue and we will fix it.