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