api-contract-guardian
API Contract Guardian
Monitor OpenAPI schema diffs between git branches, detect breaking changes, generate migration guides, and block CI pipelines on contract violations.
⭐ Star this repo if you maintain APIs — it helps other devs discover API Contract Guardian!
Why API Contract Guardian? Every API team knows the pain: a teammate renames a field, removes an endpoint, or changes a response type — and suddenly mobile apps crash, integrations break, and you’re debugging at 2 AM. Manually diffing OpenAPI specs is tedious and error-prone. API Contract Guardian automates this: compare specs between branches, detect every category of breaking change, generate human-readable migration guides, and gate your CI pipeline so breaking changes never reach production unnoticed.
Real-world scenarios:
- CI/CD gating: Block PRs that introduce breaking API changes — catch them before merge, not after deploy
- API version upgrades: When bumping v1 → v2, generate a migration guide for consumers automatically
- Microservice contract enforcement: Ensure service boundaries respect their OpenAPI contracts across deploys
- Client SDK regeneration: Know exactly what changed so SDK clients can be updated with confidence
Installation
pip install git+https://github.com/Coding-Dev-Tools/api-contract-guardian.git
Or install via Homebrew (macOS/Linux):
brew tap Coding-Dev-Tools/tap
brew install api-contract-guardian
Or install via Scoop (Windows):
scoop bucket add Coding-Dev-Tools https://github.com/Coding-Dev-Tools/scoop-bucket
scoop install api-contract-guardian
npm (Node.js wrapper — publishing pending):
# Not yet available — install via pip instead
Then run: api-contract-guardian --help
Quick Start
# Compare two spec files
api-contract-guardian check spec-v1.yaml spec-v2.yaml
# Compare git branches
api-contract-guardian check --base main --head feature-api-v2 openapi.yaml
# Generate migration guide
api-contract-guardian migrate spec-v1.yaml spec-v2.yaml --output MIGRATION.md
# CI gating (exits non-zero on breaking changes)
api-contract-guardian check spec-v1.yaml spec-v2.yaml
Features
- Breaking Change Detection: Identifies removed endpoints, changed types, renamed fields, removed properties, and more
- Migration Guide Generation: Produces human-readable markdown migration guides
- CI Gating: Exits with non-zero code when breaking changes are detected
- OpenAPI 3.x Support: Full support for OpenAPI 3.0.x and 3.1.x specs
- Git Branch Diffing: Compare specs between branches, tags, or commits
- File Comparison: Compare two local spec files directly
Breaking Changes Detected
| Category | Example |
|---|---|
| Removed endpoint | DELETE /users/{id} removed |
| Removed property | email removed from User schema |
| Changed type | age changed from integer to string |
| Required property added | phone now required in User |
| Renamed field | name renamed to fullName |
| Response format changed | 200 response type changed |
CI/CD Integration
# Fail the build if breaking changes are detected
api-contract-guardian check spec-v1.yaml spec-v2.yaml || echo "Breaking API changes found!"
Pricing
API Contract Guardian is one of eleven tools in the Revenue Holdings suite. One license covers all CLI tools.
| Plan | Price | Best For |
|---|---|---|
| Free | $0 | Individual devs, OSS — CLI only, 1 spec comparison |
| ACG Individual | $19/mo ($15 billed annually) | Professional devs — unlimited specs, CI/CD gating |
| Suite (all 11 tools) | $49/mo ($39 billed annually) | Full Revenue Holdings toolkit — 40% savings |
| Team | $79/mo ($63 billed annually) | Up to 5 devs — shared dashboards, alerts, run history |
| Enterprise | Custom | SSO, RBAC, compliance reports, dedicated support |
🔹 No lock-in: CLI works fully offline on the free tier — no telemetry, no phone-home. 🔹 Annual billing: Save 20%.
Per-Tier Features
| Feature | Free | ACG | Suite | Team | Enterprise |
|---|---|---|---|---|---|
| CLI: diff, check, migrate | ✓ | ✓ | ✓ | ✓ | ✓ |
| Unlimited spec comparisons | — | ✓ | ✓ | ✓ | ✓ |
| CI/CD gating | — | ✓ | ✓ | ✓ | ✓ |
| Migration guide generation | — | ✓ | ✓ | ✓ | ✓ |
| Custom rules / policies | — | ✓ | ✓ | ✓ | ✓ |
| Team dashboard | — | — | — | ✓ | ✓ |
| Compliance reports | — | — | — | — | ✓ |
| RBAC | — | — | — | — | ✓ |
| SSO / SAML / OIDC | — | — | — | — | ✓ |
| Priority support | Community | 24h | 24h | 8h | Dedicated |
Part of Revenue Holdings — CLI tools built by autonomous AI.
License
MIT