spec-diff-tool

---

sidebar_position: 7 pagination_next: null ai_summary: "OpenAPI spec diff tool automatically detects breaking and non-breaking changes between current branch and HEAD. Requires oasdiff installation and checkDiffs: true in OpenAPI config. Runs automatically on psy sync or manually via psy diff:openapi. Supports --fail-on-breaking flag."

OpenAPI Spec Diff Tool

This tool helps developers automatically detect breaking and non-breaking changes between the current OpenAPI specification(s) in your branch and the HEAD branch (e.g., main). It uses oasdiff under the hood.

It's designed to integrate easily into your existing workflows, either automatically or on-demand.

Prerequisites

oasdiff must be installed and available on your local system or CI environment:

brew tap oasdiff/homebrew-oasdiff
brew install oasdiff

or

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

Your project must be configured using a PsychicApp where checkDiffs: true is enabled for any OpenAPI configuration you'd like to compare.

Usage

Once checkDiffs: true is set in your OpenAPI config, there are two ways to run the diff tool:

Automatic check

pnpm psy sync

• Automatically runs OpenAPI diff checks for all configs that have checkDiffs: true.
• Recommended for use in CI pipelines or as part of your standard sync process.

Manual check

pnpm psy diff:openapi

• Manually triggers the diff comparison for enabled OpenAPI configs.
• Useful during development or pre-PR review.

Fail on Breaking Changes

Use the --fail-on-breaking, or -f flag to fail the command if any breaking changes are detected:

# when running sync
pnpm psy sync --fail-on-breaking

# when running directly
pnpm psy diff:openapi --fail-on-breaking

• This will throw an error and exit the process if breaking changes are found compared to the HEAD branch (usually main).

What It Compares

For each OpenAPI config:

• Fetches the OpenAPI spec from the HEAD branch (e.g., main)
• Compares it with the spec in your current working branch
• Uses oasdiff to generate:
  • A list of breaking changes
  • A changelog of all changes

Output Summary

The CLI output will include:

• ✅ No changes — when files match
• 🚨 Breaking changes — highlighted in red
• 📋 Changelog — a detailed diff of modifications

Example Output

🔍 Comparing current OpenAPI Specs against main...

✅ openapi: No changes

============================================================
📊 Summary: All OpenAPI files in current branch are identical to main branch
============================================================

Or, with breaking changes:

🔍 Comparing current OpenAPI Specs against main...

openapi: HAS CHANGES
   🚨 BREAKING CHANGES:
      • response removed on GET /users
   📋 CHANGELOG:
      • Removed response from GET /users

============================================================
🚨 CRITICAL: Breaking changes detected in current branch compared to main! Review before merging.
============================================================

📚 Error Reference

Error	Description
Fail on breaking	Thrown if --fail-on-breaking is used and breaking changes are detected
File not found	Raised if OpenAPI file is missing in the current working directory
Git error	Raised if file cannot be fetched from HEAD branch