API Diff Tools Compared: API Contract Guardian vs oasdiff vs Optic vs openapi-diff

The API Contract Problem

Every API is a contract between your backend and every consumer — mobile apps, SPAs, partner integrations, internal microservices. When that contract changes without anyone noticing, the result is a production incident that's hard to trace: mobile clients crash on a renamed field, partner integrations see 4xx errors for no obvious reason, frontend apps render empty data because a response shape changed.

The average API changes 2–4 times per week in active development teams. Most of those changes are additive and safe. But one in ten introduces a breaking change — a removed endpoint, a changed type, a newly-required field. Without automated diff checking, those breaks reach production silently.

Four tools take different approaches to this problem:

1. API Contract Guardian — Python CLI that diffs OpenAPI specs, detects breaking changes, generates migration guides, and gates CI pipelines.
2. oasdiff — Go-based breaking change linter with a comprehensive rule set and extensible configuration.
3. Optic — Visual diff review tool that captures API traffic and produces changelogs with team review workflows.
4. openapi-diff — Java-based schema comparator focused on backward compatibility checks with Maven/Gradle integration.

At a Glance

Capability	API Contract Guardian	oasdiff	Optic	openapi-diff
Breaking change detection	✓ 6 categories	✓ 15+ rules	~ Traffic-based	✓ Backward compat
Migration guide generation	✓ Auto-generated MD/JSON	✗	~ Changelog format	✗
CI exit codes	✓ Non-zero on break	✓ Non-zero on break	✗ Requires Cloud	✓ Maven plugin
Git branch comparison	✓ --base/--head	✓ Git integration	✗ Proxy-based	✗ File paths only
OpenAPI 3.0 + 3.1	✓ Both	✓ Both	✓ Both	~ 3.0 only
Custom rules / severity	✓ Per-change severity	✓ Configurable rules	~ Cloud-managed	✗ Hardcoded
Output formats	Rich, JSON, YAML, MD	Text, JSON, YAML, HTML, Markdown	Visual (web UI)	HTML, JSON, Markdown
Language	Python	Go	TypeScript/Node	Java
Install size	~5 MB	~12 MB (binary)	~80 MB (Node)	~30 MB (JAR + deps)
Free tier	1 comparison/session	Full (Apache 2.0)	Cloud trial only	Full (Apache 2.0)

Tool 1: API Contract Guardian

API Contract Guardian is designed around one workflow: catch breaking API changes before they reach production. Unlike linters that check style rules, it focuses exclusively on contract-breaking changes — the things that actually break clients.

Core workflow

# Install
pip install api-contract-guardian

# Compare two spec files
api-contract-guardian check spec-v1.yaml spec-v2.yaml

# Compare git branches (CI-friendly)
api-contract-guardian check --base main --head feature/new-endpoints

# Generate a migration guide for consumers
api-contract-guardian migrate spec-v1.yaml spec-v2.yaml --output MIGRATION.md

# Machine-readable output for automation
api-contract-guardian check spec-v1.yaml spec-v2.yaml --format json

What makes it different

Three things set API Contract Guardian apart:

1. Migration guide generation. When you bump your API from v1 to v2, consumers need to know what changed and how to adapt. API Contract Guardian auto-generates markdown migration guides from the spec diff — breaking changes, action items, and per-change severity. No other tool in this comparison does this.
2. CI-first design. The check command exits with a non-zero code when breaking changes are detected. It integrates with GitHub Actions, GitLab CI, and any CI system in one line. Git branch comparison is built-in, not an afterthought.
3. Per-change severity. Not every breaking change is equally severe. Removing an endpoint is critical; adding a required property to an optional schema is a warning. API Contract Guardian lets you configure severity per change category, so your CI pipeline can distinguish "block the merge" from "warn and allow."

Breaking changes detected

Category	Example	Default Severity
Removed endpoint	DELETE /users/{id} removed	Error
Removed property	email removed from User schema	Error
Changed type	age changed from integer to string	Error
Required property added	phone now required in User	Warning
Renamed field	name renamed to fullName	Error
Response format changed	200 response type changed	Error

Tool 2: oasdiff

oasdiff is the most established tool in this comparison. Built by Tufin (now part of Check Point), it's a Go CLI that focuses on breaking change detection with an extensive, well-documented rule set. It's the tool you reach for when you need comprehensive coverage and don't care about migration guides.

Core workflow

# Install (Go)
go install github.com/Tufin/oasdiff@latest

# Or Docker
docker run tufin/oasdiff breaking ./spec-v1.yaml ./spec-v2.yaml

# Check for breaking changes
oasdiff breaking ./spec-v1.yaml ./spec-v2.yaml

# With custom rules configuration
oasdiff breaking --config .oasdiff.yaml ./spec-v1.yaml ./spec-v2.yaml

# GitHub Action
- uses: tufin/oasdiff-action@main
  with:
    base-spec: spec-v1.yaml
    new-spec: spec-v2.yaml

What makes it different

oasdiff's strength is its breadth of detection rules. With 15+ built-in rules, it covers more edge cases than any other tool here — from API-sunset header changes to enum value removals to parameter constraint tightening. It's the most thorough linter for teams that want to catch every possible contract violation.

The trade-off: oasdiff detects and reports, but doesn't help consumers adapt. There's no migration guide generation, no per-change action items, and no way to say "here's what your v1 consumers need to change." It tells you what broke, not how to fix it.

Tool 3: Optic

Optic takes a fundamentally different approach: instead of comparing two static spec files, it captures real API traffic through a local proxy and infers the spec from observed requests and responses. This "traffic-first" approach means you don't need a perfectly maintained OpenAPI spec to start — Optic can discover your API surface area from live behavior.

Core workflow

# Install
npm install -g @useoptic/optic

# Start the proxy to capture traffic
optic capture --proxy-port 8000

# Review captured diffs in the web UI
optic diff:review

# Generate a changelog from reviewed changes
optic changelog

What makes it different

Optic's strength is its review workflow. Changes appear in a visual diff UI where team members can approve, reject, or comment on each change. This is ideal for larger teams where API changes need sign-off from multiple stakeholders before merging.

The trade-off is that Optic requires running a proxy and routing traffic through it, which adds operational complexity. And its CI/CD integration depends on the Optic Cloud service — there's no standalone check spec-v1 spec-v2 && exit 1 mode for local-only pipelines. If you want CI gating without a cloud dependency, this isn't the right tool.

Tool 4: openapi-diff

openapi-diff (by SourceLoop / Quobis) is the JVM-native option. It's a Java library and CLI that checks backward compatibility between two OpenAPI specs. If your stack is Java/Spring, this fits naturally into your build tooling as a Maven or Gradle plugin — no Python, Go, or Node runtime needed.

Core workflow

# Maven plugin
mvn openapi-diff:diff \
  -DoldSpec=spec-v1.yaml \
  -DnewSpec=spec-v2.yaml

# Or JAR directly
java -jar openapi-diff.jar spec-v1.yaml spec-v2.yaml

# Gradle plugin
openapiDiff {
  oldSpec = file("spec-v1.yaml")
  newSpec = file("spec-v2.yaml")
}

What makes it different

openapi-diff's strength is its JVM ecosystem fit. If you're already running Maven or Gradle in CI, adding openapi-diff as a build plugin is a natural choice — it runs in the same process, uses the same dependency management, and fails the build with standard Maven/Gradle exit codes.

The trade-off: it's limited to backward compatibility checks (is the new spec a compatible extension of the old one?). It doesn't categorize changes by severity, doesn't generate migration guides, and has limited OpenAPI 3.1 support. It also doesn't do git branch comparison — you pass two file paths and that's it.

Feature-by-Feature Comparison

Feature	API Contract Guardian	oasdiff	Optic	openapi-diff
Breaking change categories	6 categories	15+ rules	Traffic-inferred	Backward compat only
Migration guide output	✓ Markdown + JSON	✗	~ Changelog	✗
CI exit code gating	✓ Native	✓ Native	✗ Cloud-dependent	✓ Maven/Gradle
Git branch diffing	✓ Built-in	✓ Built-in	✗ Proxy-based	✗
Custom severity per rule	✓ Yes	✓ Yes	~ Cloud rules	✗ Fixed
GitHub Actions integration	✓ 1-liner	✓ Official action	✓ PR comments	✓ Maven step
GitLab CI integration	✓ Native	✓ Native	✗	✓ Gradle step
Machine-readable output	✓ JSON, YAML	✓ JSON, YAML, HTML	~ API	✓ JSON, HTML, MD
OpenAPI 3.1 support	✓ Full	✓ Full	✓ Full	~ Partial
Offline / air-gapped	✓ Yes	✓ Yes	✗ Needs cloud	✓ Yes
No spec required (traffic capture)	✗	✗	✓ Yes	✗
Visual diff review UI	✗	✗	✓ Web UI	✗

The Migration Guide Advantage: Why Consumer Communication Matters

Here's the scenario most API teams know too well: you bump your API from v1 to v2, the backend team updates their code, CI passes, and everything looks fine. Then your mobile app crashes. Your partner integration breaks. Your frontend renders empty data. Why? Because nobody told the consumers what changed.

Detection is half the battle. The other half is communicating changes to consumers in a format they can act on.

This is where API Contract Guardian's migration guide generation creates a workflow that the other tools don't address:

# Generate a consumer-ready migration guide
api-contract-guardian migrate spec-v1.yaml spec-v2.yaml --output MIGRATION.md

# The output includes:
# - Summary of all changes (breaking + non-breaking)
# - Per-change action items with code examples
# - Severity labels (error/warning/info)
# - Versioned sections organized by endpoint

# Also available in JSON for custom tooling
api-contract-guardian migrate spec-v1.yaml spec-v2.yaml --format json --output migration.json

oasdiff tells you what broke. Optic shows you what changed visually. openapi-diff tells you if the new spec is backward-compatible. Only API Contract Guardian produces an actionable document that your API consumers can follow to update their code.

CI/CD Integration Compared

All four tools can run in CI, but the setup complexity varies significantly:

API Contract Guardian

# GitHub Actions
- name: Check API contract
  run: |
    pip install api-contract-guardian
    api-contract-guardian check \
      --base origin/main \
      --head HEAD \
      --format json \
      --output contract-check.json

# GitLab CI
check-api-contract:
  script:
    - pip install api-contract-guardian
    - api-contract-guardian check --base $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --head HEAD

oasdiff

# GitHub Actions (official action)
- uses: tufin/oasdiff-action@main
  with:
    base-spec: spec-v1.yaml
    new-spec: spec-v2.yaml

# Or CLI directly
- name: Check API contract
  run: |
    docker run tufin/oasdiff breaking spec-v1.yaml spec-v2.yaml

Optic

# Requires Optic Cloud authentication
- name: Optic diff check
  run: |
    npm install -g @useoptic/optic
    optic diff:check --spec spec-v2.yaml
  env:
    OPTIC_API_KEY: ${{ secrets.OPTIC_API_KEY }}

openapi-diff

# Maven
- name: OpenAPI Diff
  run: mvn openapi-diff:diff -DoldSpec=spec-v1.yaml -DnewSpec=spec-v2.yaml

# Or JAR
- name: OpenAPI Diff
  run: java -jar openapi-diff.jar spec-v1.yaml spec-v2.yaml

API Contract Guardian and oasdiff are the easiest to add to any CI pipeline — one install command, one check command. openapi-diff is natural for Maven/Gradle projects. Optic requires cloud authentication, which adds a dependency and a secret to manage.

When to Use Which

The Complementary Stack

Many teams combine tools based on what they need at each stage of the API lifecycle:

• API Contract Guardian for CI gating — Block merges that break the contract. Generate migration guides for consumers.
• oasdiff for thorough rule coverage — Run alongside Contract Guardian for additional edge case detection that goes beyond the core 6 categories.
• Optic for review workflows — Use the visual diff UI when API changes need sign-off from multiple stakeholders before merging.
• openapi-diff for JVM builds — Add backward compatibility checks as a Maven/Gradle step in Java projects.

# Typical workflow:
# 1. Develop: Make API changes in feature branch
# 2. Diff: API Contract Guardian check (CI gating — block on breaking changes)
# 3. Migrate: API Contract Guardian migrate (auto-generate migration guide)
# 4. Review: Optic visual diff (team review for significant changes)
# 5. Lint: oasdiff breaking (additional rule coverage for edge cases)
# 6. Build: openapi-diff (Maven/Gradle compat check for Java consumers)
# 7. Merge: Contract protected, consumers informed

Cost Comparison

Factor	API Contract Guardian	oasdiff	Optic	openapi-diff
License	MIT (Free tier)	Apache 2.0	Proprietary (Cloud)	Apache 2.0
Free tier limits	1 comparison/session	None	Trial only	None
Paid tier	$19/mo ACG	N/A	$39/seat/mo	N/A
Runtime dependency	Python 3.10+	Go binary or Docker	Node.js + Cloud	JVM 8+
Install size	~5 MB	~12 MB	~80 MB + cloud	~30 MB
Setup time	30 seconds	1 minute	10 minutes	5 minutes

Install API Contract Guardian

# pip
pip install api-contract-guardian

# Check your API for breaking changes
api-contract-guardian check spec-v1.yaml spec-v2.yaml

# Generate a migration guide for consumers
api-contract-guardian migrate spec-v1.yaml spec-v2.yaml --output MIGRATION.md

# CI gating (exit non-zero on breaking changes)
api-contract-guardian check --base main --head feature/api-v2

Star API Contract Guardian on GitHub

Related Reading

• Block PRs on Breaking API Changes: CI/CD Gating Tutorial — step-by-step GitHub Actions and GitLab CI setup
• Generate API Migration Guides Automatically — v1 to v2 without missing a change
• OpenAPI Diffing Tools Compared: API Contract Guardian vs Spectral vs OAS Diff — 3-tool comparison with Spectral
• Catch Breaking API Changes in CI — why CI gating matters
• Stop Breaking Production with Silent API Changes — the real cost of undetected contract violations