Api Contract Validator

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.