Api Contract Validator Pro

Catch breaking API changes, spec drift and lint errors in one offline CI gate, with a PR-ready report and no npm, Go or Java installs.

Free vs Pro

Free is the procedure and the external-tool recipes (Spectral, Redocly, oasdiff, openapi-diff, Schemathesis); it ships no scripts. Pro is the four offline Python tools (lint, diff, scan and gate), the rule-code engine, machine output in JSON, Markdown and SARIF, the baseline allowlist workflow, and the report renderer.

Upgrade Path

Install the Pro skill and keep the free one for the external-tool recipes. Both run the same five-step procedure, so nothing you already do changes: Pro simply makes steps 2 to 5 runnable offline.

Tags: openapi, api-contracts, breaking-changes, spec-linting, drift-detection, sarif, ci-cd, offline

Version: 1.0.0

The Problem

The free way to check an API contract is a procedure that leans on other people's tools: Spectral and Redocly from npm, oasdiff from Go, openapi-diff from Java. On a locked-down CI runner, a fresh laptop or a Python-only container, none of that is installed, and an agent asked to "check for breaking changes" falls back to skimming the diff by eye.

Even where the tools exist, three separate commands give three separate outputs and three exit conventions. There is no single pass or fail, no way to say "we already accepted that break, stop failing on it", and nothing a reviewer can open in one page.

What You Get

• An offline linter with 12 rules (L001 to L012) for OpenAPI 3.0, 3.1 and Swagger 2.0: missing summaries, trailing slashes, duplicate operationIds, unresolved refs, undefined security schemes and more.
• A breaking-change diff with 8 blocking codes (BREAK-001 to BREAK-008) and 5 informational codes (WARN-001 to WARN-005), plus --fail-on and --allow-version-bump for planned /v1/ to /v2/ moves.
• A static drift scan in both directions for FastAPI, Flask, Express and Go net/http, with file and line for every code-only route. Findings are labelled static review.
• One CI gate with exit codes 0 pass, 1 contract failure, 2 tool error, and a baseline allowlist so an accepted break stops failing later runs.
• A report renderer: single-file HTML, JSON, Markdown and SARIF 2.1.0 from the same run.
• A rule reference and CI recipes for GitHub Actions and GitLab that install only Python and PyYAML.
• A test suite (stdlib unittest) that covers every rule code, determinism and the exit codes.

Why This Beats Prompting It Yourself

A prompt gets a read-through. This gets a program: the same input gives byte-identical JSON on every run, every finding has a stable code, and the exit code means the same thing in every script. Nothing is fetched and nothing is executed: the scripts make no network calls and start no child processes, and they only write to the --out path you pass. The drift scan is honest about being pattern-based, and says so in every finding.

Example Session

The numbers below come from the bundled demo spec pair (a base spec and a "sprint" version of it) and the bundled demo source file. They are recorded in examples/demo/EXPECTED.md, they are a fixture and not a customer result, and the test suite re-checks the gate SUMMARY line against that file.

Request: gate the v2 demo spec against v1 and the demo source.

$ python3 scripts/contract_gate.py --spec examples/demo/openapi.v2.yaml --base examples/demo/openapi.v1.yaml --src examples/demo/src
== Spec lint: 6 finding(s) ==
ERR L006  path '/orders/{orderId}/' has a trailing slash
== Implementation drift: 6 finding(s) ==
ERR DRIFT-001  GET /health  route GET /health exists in code but has no matching operation in the spec  [static review]
== Breaking changes: 19 finding(s) ==
ERR BREAK-004  POST /orders  new required request body property 'currency'
ERR BREAK-007  GET /users  operation now requires authentication

Lines above are trimmed to a few of the findings (the file and line suffix is dropped). The run ends with the SUMMARY line, which reports lint at 3 errors and 3 warnings, drift at 6 findings, breaking changes at 13 errors and 6 warnings, and GATE FAIL with exit code 1.

The 13 breaking errors span 7 distinct codes. Three of them are one edit to a shared schema (a removed field), counted once per operation that returns it. Running the diff of the v1 spec against itself reports 0 findings and exits 0.

Use Cases

• Gate every pull request that touches the spec or the route code, on a runner with nothing but Python.
• Upload SARIF to GitHub code scanning so contract findings show up on the changed lines.
• Hand reviewers one HTML page with a PASS or FAIL banner instead of three terminal logs.
• Record a deliberate breaking change in the baseline file, with a reason, and keep the gate green for everything else.
• Check a Swagger 2.0 to OpenAPI 3 migration lost no paths, methods or response fields.

Known Limitations

• Drift is static review. It reads source as text and cannot see runtime-only behaviour such as middleware, feature flags or dynamically built routes.
• Handler extraction is pattern-based, so unusual routing frameworks, heavy metaprogramming and mounted router prefixes can be missed.
• YAML specs need PyYAML; JSON specs need only the standard library.
• OpenAPI and Swagger over HTTP only. No gRPC or GraphQL.
• It does not replace Spectral or oasdiff when you need their full rulesets or custom rules.