What is api-contract-validator?

The API Contract Validator is a comprehensive Claude skill designed to ensure API reliability and seamless integration across software architectures. It automates the validation of OpenAPI/Swagger specifications, detects breaking changes between versions, and facilitates consumer-driven contract testing. By bridging the gap between API design and implementation through automated type generation and mock creation, it helps development teams maintain high-quality, compatible, and well-documented services while preventing costly integration failures.

When should I use api-contract-validator?

api-contract-validator is useful in the following scenarios: • Automated Breaking Change Detection: Integrate into CI/CD pipelines to compare API versions (e.g., using oasdiff) and prevent the deployment of updates that would break existing client integrations. • Type-Safe Full-Stack Development: Generate TypeScript interfaces and types directly from OpenAPI specifications to ensure that frontend consumers and backend providers remain perfectly synchronized. • Consumer-Driven Contract Testing: Utilize Pact-based testing to define and verify expectations between microservices, ensuring that changes in a provider service do not disrupt dependent consumers. • API Specification Quality Assurance: Validate local Swagger or OpenAPI files against standard schemas to ensure documentation accuracy, compliance, and readiness for mock generation.

name	api-contract-validator
description	"Validate API contracts and ensure compatibility. Use when checking OpenAPI specs, running contract tests, detecting breaking changes, or generating types from API specifications."

API Contract Validator

Ensure API compatibility and prevent breaking changes through contract testing

Quick Commands

# Validate OpenAPI spec
npx @apidevtools/swagger-cli validate api-spec.yml

# Run contract tests
npm run test:contracts

# Check breaking changes
npx oasdiff breaking api-v1.yml api-v2.yml

# Generate types from spec
npx openapi-typescript api-spec.yml --output types.ts

Core Functionality

Key Features

Schema Validation: OpenAPI/Swagger spec validation
Contract Testing: Consumer-driven contracts
Breaking Change Detection: API compatibility checking
Mock Generation: Generate mocks from contracts
Type Safety: TypeScript types from API specs

Detailed Information

For comprehensive details, see:

cat .claude/skills/api-contract-validator/references/contract-testing-guide.md

cat .claude/skills/api-contract-validator/references/openapi-best-practices.md

cat .claude/skills/api-contract-validator/references/versioning-strategy.md

Usage Examples

Example 1: Validate API Response

import { APIContractValidator } from '@j0kz/api-contract-validator';

const validator = new APIContractValidator('./api-spec.yml');

// Validate response against contract
const response = await fetch('/api/users/123');
const validation = await validator.validateResponse(
  'GET',
  '/users/{id}',
  response
);

if (!validation.valid) {
  console.error('Contract violation:', validation.errors);
}

Example 2: Consumer-Driven Contracts

// Consumer defines expectations
const contract = {
  consumer: 'mobile-app',
  provider: 'user-service',
  interactions: [{
    description: 'get user by id',
    request: {
      method: 'GET',
      path: '/users/123'
    },
    response: {
      status: 200,
      body: {
        id: '123',
        name: 'John Doe',
        email: 'john@example.com'
      }
    }
  }]
};

await validator.verifyContract(contract);

Contract Testing Patterns

Pact Testing

const { Pact } = require('@pact-foundation/pact');

const provider = new Pact({
  consumer: 'MyConsumer',
  provider: 'MyProvider'
});

// Define interactions
await provider.addInteraction({
  state: 'user exists',
  uponReceiving: 'a request for user',
  withRequest: {
    method: 'GET',
    path: '/users/1'
  },
  willRespondWith: {
    status: 200,
    body: expectedUser
  }
});

Configuration

{
  "api-contract-validator": {
    "specFile": "./api/openapi.yml",
    "strict": true,
    "allowAdditionalProperties": false,
    "contracts": {
      "directory": "./contracts",
      "publish": true,
      "broker": "https://pact-broker.example.com"
    },
    "breaking": {
      "allowRemoval": false,
      "allowTypeChange": false,
      "allowRequired": false
    }
  }
}

CI/CD Integration

# GitHub Actions
- name: Validate API Contract
  run: |
    npx @j0kz/api-contract-validator validate
    npx @j0kz/api-contract-validator check-breaking

- name: Publish Contracts
  run: npx @j0kz/api-contract-validator publish

Notes

Supports OpenAPI 3.0, Swagger 2.0, and AsyncAPI
Integrates with Pact for consumer-driven contracts
Can generate API documentation automatically
Supports GraphQL schema validation

api-contract-validator

When & Why to Use This Skill

Use Cases