API Contract Validator

A CLI tool that validates your API responses against OpenAPI/Swagger specifications. Ensure your API implementation matches your documented contract with automated schema validation, status code checks, and comprehensive error reporting.

Features

• OpenAPI 3.0 Support: Full support for OpenAPI 3.0 specifications
• Schema Validation: Validates response bodies against JSON schemas using AJV
• Status Code Checking: Ensures responses use documented status codes
• Batch Testing: Validate multiple endpoints from a configuration file
• Detailed Reporting: Get comprehensive error reports with expected vs. received values
• CI/CD Integration: Perfect for automated testing pipelines
• Export Reports: Generate JSON reports for further analysis

Quick Start

Installation

npm install -g api-contract-validator

Or use directly with npx:

npx api-contract-validator

Basic Usage

Validate a single endpoint:

api-contract-validator validate \
  --spec ./openapi.yaml \
  --url http://localhost:3000 \
  --path /api/users \
  --method GET

List all endpoints from your spec:

api-contract-validator list --spec ./openapi.yaml

Commands

validate

Validate a single API endpoint against your OpenAPI spec.

api-contract-validator validate \
  --spec <path-to-spec> \
  --url <api-base-url> \
  --path <endpoint-path> \
  --method <http-method> \
  [--data <json-body>] \
  [--headers <json-headers>]

Options:

• -s, --spec <path> - Path to OpenAPI/Swagger spec file (required)
• -u, --url <url> - Base URL of the API (required)
• -p, --path <path> - API endpoint path, e.g., /api/users (required)
• -m, --method <method> - HTTP method: GET, POST, PUT, DELETE, etc. (required)
• -d, --data <json> - Request body as JSON string (optional)
• -h, --headers <json> - Request headers as JSON string (optional)

Example:

api-contract-validator validate \
  --spec ./openapi.yaml \
  --url http://localhost:3000 \
  --path /api/users \
  --method POST \
  --data '{"name":"John Doe","email":"john@example.com"}' \
  --headers '{"Authorization":"Bearer token123"}'

validate-all

Validate multiple endpoints from a test configuration file.

api-contract-validator validate-all \
  --spec <path-to-spec> \
  --url <api-base-url> \
  --config <test-config-path> \
  [--output <report-path>]

Options:

• -s, --spec <path> - Path to OpenAPI/Swagger spec file (required)
• -u, --url <url> - Base URL of the API (required)
• -c, --config <path> - Path to test configuration JSON file (required)
• -o, --output <path> - Output report to file (optional)

Test Configuration Format:

[
  {
    "path": "/api/users",
    "method": "GET"
  },
  {
    "path": "/api/users",
    "method": "POST",
    "data": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "headers": {
      "Authorization": "Bearer token123"
    }
  }
]

Example:

api-contract-validator validate-all \
  --spec ./openapi.yaml \
  --url http://localhost:3000 \
  --config ./test-config.json \
  --output ./validation-report.json

list

List all endpoints defined in your OpenAPI specification.

api-contract-validator list --spec <path-to-spec>

Example:

api-contract-validator list --spec ./openapi.yaml

Use Cases

Development Testing

Validate your API during development to catch contract violations early:

npm run dev & # Start your API server
api-contract-validator validate-all --spec ./openapi.yaml --url http://localhost:3000 --config ./tests.json

CI/CD Pipeline

Add to your GitHub Actions workflow:

- name: Validate API Contract
  run: |
    npm start &
    sleep 5
    npx api-contract-validator validate-all \
      --spec ./openapi.yaml \
      --url http://localhost:3000 \
      --config ./api-tests.json \
      --output ./contract-report.json

Pre-Deployment Checks

Validate staging environment before production deployment:

api-contract-validator validate-all \
  --spec ./openapi.yaml \
  --url https://staging.api.example.com \
  --config ./production-tests.json \
  --output ./staging-validation.json

Error Types

The validator reports several types of errors:

• schema: Response body doesn't match the defined JSON schema
• status: Response status code not documented in the spec
• header: Required response headers are missing
• missing: Endpoint or method not found in the spec

Tech Stack

• Commander.js: CLI framework
• Swagger Parser: OpenAPI spec parsing and validation
• AJV: JSON schema validation with format support
• Axios: HTTP client for API calls
• Chalk: Colorful terminal output
• TypeScript: Type-safe development

Output Example

Validating 3 endpoints...

✓ PASS GET /api/users (200)
✗ FAIL POST /api/users (422)
  └─ [schema] must have required property 'email'
✓ PASS GET /api/users/123 (200)

──────────────────────────────────────────────────
Total: 3 | Pass: 2 | Fail: 1

Development

Clone and install:

git clone https://github.com/patrickboxfordpartners/api-contract-validator.git
cd api-contract-validator
npm install

Build:

npm run build

Run in development:

npm run dev -- validate --spec ./openapi.yaml --url http://localhost:3000 --path /api/users --method GET

License

MIT