api-contract-checker

Validate runtime API responses against OpenAPI specifications to detect contract drift.

Features

• Validate API responses against OpenAPI 3.x specifications
• Automatic path parameter matching (e.g., /users/{id} matches /users/123)
• Detect contract drift between backend implementations and API documentation
• CLI and programmatic API for easy integration
• CI/CD pipeline integration support
• Clear error reporting for failed validations
• Support for both JSON and YAML spec formats

Installation

npm install api-contract-checker

Usage

CLI

# Validate a response against your OpenAPI spec
api-contract-checker --spec openapi.yaml --request response.json

Request file format:

{
  "path": "/api/users/123",
  "method": "GET",
  "statusCode": 200,
  "responseBody": {
    "id": 123,
    "name": "John Doe"
  }
}

Programmatic API

import { checkContract } from 'api-contract-checker';

const result = checkContract({
  specPath: './openapi.yaml',
  path: '/api/users/123',
  method: 'GET',
  statusCode: 200,
  responseBody: {
    id: 123,
    name: 'John Doe'
  }
});

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

Advanced Usage

import { ContractValidator, SpecLoader } from 'api-contract-checker';

// Load spec once and reuse validator
const spec = SpecLoader.loadFromFile('./openapi.yaml');
const validator = new ContractValidator(spec);

// Validate multiple responses
const result = validator.validateResponse('/api/users', 'GET', 200, responseData);

CI Integration

Add to your test suite or CI pipeline:

// test/contract.test.js
const { checkContract } = require('api-contract-checker');

test('API response matches contract', () => {
  const result = checkContract({
    specPath: './openapi.yaml',
    path: '/api/users',
    method: 'GET',
    statusCode: 200,
    responseBody: apiResponse
  });

  expect(result.valid).toBe(true);
});

License

MIT