- Home
- Skills
- APIs & Backend
- api-contract-validator
More screenshots
Works with the AI Agents you already use
Api Contract Validator
Your OpenAPI spec says `GET /users/{id}` returns a `User` object with `name`, `email`, and `role`.
Free
api-contract-validator
Example session with this skill installed
"Validate the API spec against the implementation and check for breaking changes vs. main branch."
- Read your context and instructions
- Compiled the api-contract-validator
# API Contract Validation Report
SPEC LINTING (SPECTRAL)
═══════════════════════
- Errors: 0 | Warnings: 3 | Info: 1
- Warning: operation-description missing on DELETE /api/v1/sessions
- Warning: info-contact missing (add contact email)
- Warning: oas3-unused-component: PaymentStatus (defined but never referenced)
IMPLEMENTATION VS. SPEC (DREDD)
═══════════════════════════════
- Tests: 47 | Passed: 44 | Failed: 3
Endpoint Method Expected Actual Status
─────────── ────── ─────────────────── ───────────────────── ────────────────────────
/users/{id} GET 200 → User 200 → User ✅
/users/{id} GET 404 → NotFoundError 404 → string ❌ Schema mismatch
/payments POST 201 → Payment 500 → Error ❌ Unimplemented endpoint
/orders GET 200 → [Order] 200 → {orders: [...], ❌ Wrapper not in spec
total}
BREAKING CHANGES VS. MAIN
═════════════════════════
- oasdiff breaking: 2 breaking changes detected
1. REMOVED: GET /api/v1/legacy-export (used by mob
Connects securely to your tools. The creator never sees your data.
About this skill
The Problem
Your OpenAPI spec says GET /users/{id} returns a User object with name, email, and role. The actual implementation returns name, email, and permissions — a field rename nobody documented. A consumer team builds against the spec, ships to production, and their app breaks because user.role is undefined. They blame your API. You blame the spec. The spec blames the developer who made the change six months ago without updating it.
This is spec drift — the most common failure mode in API-first teams. The spec says one thing, the code does another. Status codes change without documentation. Required fields become optional. New response codes appear without spec entries. Breaking changes ship in patch releases because nobody ran a diff between spec versions.
What You Get
- OpenAPI spec linting — Spectral, Redocly CLI, and IBM openapi-validator integration with custom rulesets for operation descriptions, trailing slashes, typed enums, unused components, and path conventions
- Implementation-vs-spec validation — runtime contract testing with Dredd (sends real HTTP requests and validates responses), plus framework-specific middleware (express-openapi-validator, FastAPI auto-validation, connexion for Flask, kin-openapi for Go)
- Breaking change detection — oasdiff and openapi-diff comparisons between spec versions, identifying removed endpoints, changed response schemas, new required fields, and modified status codes
- CI/CD integration templates — GitHub Actions (spectral + oasdiff) and GitLab CI pipelines that block merges on spec errors or breaking changes
- Quality gate matrix — five gates before any API-related merge: spec syntax valid, no breaking changes, runtime compliance, response schema match, unused components clean
- Multi-file spec support — Redocly bundling for
$ref-heavy specs that fail validation due to cross-file reference resolution
Why This Beats Prompting It Yourself
Manually comparing an OpenAPI spec against an implementation requires reading every endpoint, every response schema, every status code, and cross-referencing with actual route handlers. The validator automates this with Dredd (runtime contract testing), Spectral (spec linting), and oasdiff (breaking change detection) — then integrates into CI so every PR that touches API code is automatically checked against the spec. The result: spec drift gets caught in the PR review, not in the consumer's production incident.
Example Session
You: "Validate the API spec against the implementation and check for breaking changes vs. main branch."
Agent:
# API Contract Validation Report
SPEC LINTING (SPECTRAL)
═══════════════════════
- Errors: 0 | Warnings: 3 | Info: 1
- Warning: operation-description missing on DELETE /api/v1/sessions
- Warning: info-contact missing (add contact email)
- Warning: oas3-unused-component: PaymentStatus (defined but never referenced)
IMPLEMENTATION VS. SPEC (DREDD)
═══════════════════════════════
- Tests: 47 | Passed: 44 | Failed: 3
Endpoint Method Expected Actual Status
─────────── ────── ─────────────────── ───────────────────── ────────────────────────
/users/{id} GET 200 → User 200 → User ✅
/users/{id} GET 404 → NotFoundError 404 → string ❌ Schema mismatch
/payments POST 201 → Payment 500 → Error ❌ Unimplemented endpoint
/orders GET 200 → [Order] 200 → {orders: [...], ❌ Wrapper not in spec
total}
BREAKING CHANGES VS. MAIN
═════════════════════════
- oasdiff breaking: 2 breaking changes detected
1. REMOVED: GET /api/v1/legacy-export (used by mob
Use Cases
- Pre-merge API gate — block PRs that introduce breaking changes or spec drift
- API-first workflow enforcement — validate that implementations match specs written before coding
- Consumer-team coordination — run breaking change detection before releasing API updates
- OpenAPI version migration — compare Swagger 2.0 specs against OpenAPI 3.0 rewrites
- Documentation accuracy audit — verify that API docs reflect the actual running service
Known Limitations
Dredd-based runtime testing requires the API server to be running — it cannot validate implementation against a spec offline. Circular $ref patterns in OpenAPI 3.0 specs may cause tool hangs; upgrade to OpenAPI 3.1 or flatten references as a workaround. The validator covers HTTP/REST APIs only — gRPC, GraphQL, and WebSocket contracts require different tooling.
Upgrade to Pro
Need this to run offline, in one command, with stable exit codes and a PR-ready report? API Contract Validator Pro ships four pure-Python tools (lint, diff, drift scan, gate) with JSON, Markdown and SARIF output, plus a baseline allowlist for accepted breaks.
Dredd-based runtime testing requires the API server to be running — it cannot validate implementation against a spec offline. Circular $ref patterns in OpenAPI 3.0 specs may cause tool hangs; upgrade to OpenAPI 3.1 or flatten references as a workaround. The validator covers HTTP/REST APIs only — gRPC, GraphQL, and WebSocket contracts require different tooling.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
17 uses
Times used to date
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 5 months ago
- Free with an Agensi account
Requires