openapi-mock-darksol

Drop an OpenAPI spec. Get a deterministic mock server. No excuses.

Turn any OpenAPI 3.x spec into a fully functional mock API server with strict validation, seeded deterministic output, and controllable failure injection. Frontend, QA, and integration teams stop waiting — start shipping.

Install

npm install openapi-mock-darksol

Quick Start

# Run a mock server from any OpenAPI spec
npx openapi-mock-darksol mock:start --spec ./petstore.yaml

# Deterministic output — same seed, same responses, every time
npx openapi-mock-darksol mock:start --spec ./api.yaml --seed 42 --examples first

# Strict mode — validate every request against the spec
npx openapi-mock-darksol mock:start --spec ./api.yaml --strict --verbose

# Force an error on any request with a header
curl -H "x-mock-error: 503" http://localhost:4010/pets/1

# Check your spec is mockable before CI runs
npx openapi-mock-darksol mock:check --spec ./api.yaml

Mock Server

The core command. Parses your OpenAPI 3.x spec, builds routes, and serves mock responses.

openapi-mock mock:start --spec ./spec.yaml --port 4010

Response resolution priority:

1. example field on the media type
2. examples collection (first or random selection)
3. Schema-based generation (deterministic with --seed)
4. Fallback { ok: true }

Options

| Option | Type | Default | Description | |---|---|---|---| | --spec | string | required | Path or URL to OpenAPI 3.x spec | | --config | string | — | YAML/JSON config for per-operation behavior | | --port | number | 4010 | Server port | | --seed | number | 42 | Seed for deterministic generation | | --examples | first\|random | first | Example selection strategy | | --strict | boolean | false | Validate request params/body against schema | | --cors | boolean | false | Enable CORS middleware | | --watch | boolean | false | Hot-reload on spec/config file changes | | --error-rate | number | 0 | Global random error injection rate (0–1) | | --error-status | number | 500 | HTTP status for injected errors | | --verbose | boolean | false | Log every request with route + source info |

Strict Validation

With --strict, every incoming request is validated against the OpenAPI spec using AJV:

• Path parameters — type and presence checks
• Query parameters — required fields, schema validation
• Headers — parameter schema enforcement
• Request body — full JSON schema validation

openapi-mock mock:start --spec ./api.yaml --strict

# Invalid request body returns 400 with details
curl -X POST http://localhost:4010/pets \
  -H "Content-Type: application/json" \
  -d '{"name": 123}'
# → 400 { error: { code: "VALIDATION_ERROR", details: [...] } }

Error Injection

Simulate failures globally or per-operation. Test your frontend's error handling without touching backend code.

# 20% of requests fail with 503
openapi-mock mock:start --spec ./api.yaml --error-rate 0.2 --error-status 503

# Force a specific error on one request
curl -H "x-mock-error: 429" http://localhost:4010/pets
# → 429 { error: { code: "MOCK_ERROR", message: "Simulated error" } }

Per-operation config via --config:

operations:
  createPet:
    errorRate: 0.5
    errorStatus: 422

Deterministic Generation

Same seed + same spec = same output. Every time. Built on a seeded PRNG (xmur3 + mulberry32) — no Math.random() anywhere.

# These two runs produce identical responses
openapi-mock mock:start --spec ./api.yaml --seed 42
openapi-mock mock:start --spec ./api.yaml --seed 42

Schema generation handles:

• string (plain, email, uuid, date-time, date formats)
• integer and number with min/max bounds
• boolean, enum, array with minItems/maxItems
• object with nested properties and required fields
• oneOf, anyOf, allOf composition
• default values respected when defined

Snapshot Build

Freeze mock responses to disk for offline use, test fixtures, or CI snapshots.

openapi-mock mock:build --spec ./api.yaml --out ./.mock-snapshot --seed 42

Generates one JSON file per operation plus a routes.json manifest:

{
  "spec": "./api.yaml",
  "generatedAt": "2026-03-07T12:00:00.000Z",
  "routes": [
    {
      "operationId": "listPets",
      "method": "GET",
      "path": "/pets",
      "statusCode": 200,
      "source": "example"
    }
  ]
}

Spec Check

Validate that your spec is parseable and has mockable responses — perfect for CI gates.

openapi-mock mock:check --spec ./api.yaml
# → mock:check passed
# → Routes: 8
# → Mockable routes: 7

Watch Mode

Auto-reload routes when your spec or config file changes. No restart needed during development.

openapi-mock mock:start --spec ./api.yaml --config ./mock.yaml --watch

Architecture

1. Parse & dereference — OpenAPI spec loaded and fully resolved via @apidevtools/swagger-parser
2. Route building — every path × method → operation with parameters, request body, and response schemas
3. Request matching — incoming requests matched against OpenAPI path templates with parameter extraction
4. Response resolution — example → examples → schema generation → fallback, in that order
5. Seeded PRNG — deterministic output tied to seed + operation + request fingerprint

Limitations

• OpenAPI 3.x only (no Swagger 2.0)
• Request body validation targets JSON payloads
• No auth-flow emulation (OAuth/JWT lifecycle)
• No stateful scenario engine (yet)

Security

• Do not run mocks against untrusted specs without review
• Never commit secrets in config files
• Mock server is for development — not production traffic

Built with teeth. 🌑