Instantly spin up realistic API mocks from your OpenAPI spec — zero config, one command.

Install

npm install -g @trillionclues/contour
# or
pnpm add -g @trillionclues/contour
# or
npx @trillionclues/contour start openapi.yaml

Requires Node.js >= 18

Usage

contour start ./api/openapi.yaml          # local file
contour start https://example-openapi.com/api.json  # remote URL
contour start curl -s http://127.0.0.1:3001/pet/findByStatus?status=pending | jq '.'   # Swagger UI page

Your mock API is running at http://0.0.0.0:3001 with realistic, type-safe responses.

Sample Remote URL

https://petstore.swagger.io/v2/swagger.json (JSON format)
https://petstore.swagger.io/v2/swagger.yaml (YAML format)

Options

contour start <spec> [options]

  -p, --port <number>       Port (default: 3001)
  --stateful                Persist POST/PUT/DELETE data in memory
  --deterministic           Reproducible data for E2E tests
  --delay <min-max>         Simulate latency, e.g. --delay 200-500
  --error-rate <percent>    Simulate failures, e.g. --error-rate 10
  --require-auth            Require Bearer token
  -H, --host <address>      Host address to bind to (default: 0.0.0.0)
  --strict-validation       Enable strict request validation against the OpenAPI schema
  --strict-level <mode>     Validation strictness: hard (reject) or soft (warn)

Examples

contour start api.yaml --port 4000 --delay 100-300
contour start api.yaml --deterministic --stateful
contour start api.yaml --error-rate 15 --delay 500-2000
contour start api.yaml --host [IP_ADDRESS]

Features

• Smart data generation — property-name heuristics produce real names, emails, addresses
• Stateful mode — POST creates, GET retrieves, DELETE removes — full CRUD without a database
• Request validation — Enable --strict-validation to validate all request bodies and parameters against your schema, returning 400 with details for invalid payloads.
• x-contour-* / x-strict extensions — fine-tune per-endpoint behavior directly in your spec:

/users:
  get:
    x-contour-count: 20              # array size override
    x-contour-delay: 1000            # per-route latency (ms)
    x-contour-deterministic: true    # consistent data per endpoint
    x-strict: true                   # strictly validate this endpoint

• Spec caching — contour cache list / contour cache clear
• Offline support — cached specs work without network

Framework Integration

Next.js / React

{
  "scripts": {
    "dev": "concurrently \"contour start api.yaml\" \"next dev\"",
    "test:e2e": "contour start api.yaml --deterministic & playwright test"
  }
}

Vite

// vite.config.js
export default defineConfig({
  server: { proxy: { '/api': 'http://0.0.0.0:3001' } }
});

Contributing

Contributions are welcome! See CONTRIBUTING.md.

License

MIT © trillionclues