More screenshots

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Api Contract Validator

    3

    Your OpenAPI spec says `GET /users/{id}` returns a `User` object with `name`, `email`, and `role`.

    Free

    17 usesSecurity scanned
    api-contract-validator

    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.

    Pro version

    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. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 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

    openapi-to-postmanv2
    Node.js
    Python

    Permissions

    Terminal / Shell
    Listed5 months ago
    Updated27 days ago

    What's inside

    Frequently Asked Questions

    The skill automates the validation of OpenAPI/Swagger specs against real server implementations, catching schema mismatches and breaking changes that would otherwise break frontend or mobile applications.

    This skill is designed to work with major AI coding assistants and orchestration frameworks that support CLI tool execution, including those used in CI/CD pipelines like GitHub Actions.

    The skill supports standard OpenAPI (Swagger) versions 2.0, 3.0, and 3.1, and integrates with popular tools like Spectral, Redocly, and oasdiff for comprehensive linting and diffing.

    Setup is straightforward; once integrated, the skill uses your existing specs and server endpoint URLs to configure automated testing workflows and CI/CD guardrails.

    The package includes the core validation logic, pre-configured linting rulesets, CI/CD templates for GitHub and GitLab, and detailed documentation on implementing runtime checks for various backend frameworks.

    Yes, the skill specializes in 'diffing' spec versions to proactively flag breaking changes—such as removed required fields or altered data types—before they are merged into production.

    New in APIs & Backend