Mock server

Spin up an Express-backed fake of your API in seconds — no spec stitching, no manual handler stubs. doctreen mock reads any OpenAPI 3.x document (from a live /docs URL or a local JSON file) and synthesises responses from each operation's schema.

Languages: ships in the npm package and the PHP package (vendor/bin/doctreen mock — CRUD short-circuits, latency/error injection, optional Faker). Because it feeds on any OpenAPI 3.x document, either CLI can mock a service written in any language. A native Python mock server is planned.

# From a running doctreen-enabled server
npx doctreen mock --from http://localhost:3000/docs --port 4000

# From an OpenAPI file on disk
npx doctreen mock --from ./openapi.json --port 4000

# With latency + random error injection (shake out frontend error paths)
npx doctreen mock --from ./openapi.json --latency 100-500 --error-rate 0.1

PHP projects get the same command from Composer:

vendor/bin/doctreen mock --from https://api.example.com/docs --port 4000

What you get

• Schema-faithful responses generated from each operation's success response. $ref, oneOf/anyOf/allOf, enum, const, default, and per-operation examples are all respected.
• CRUD short-circuits. When the spec exposes /resource + /resource/:id, POST actually creates a row in an in-memory store, GET reads it back, PATCH/PUT mutate it, DELETE removes it. Envelope responses ({ products: [...], total, filters }) are detected and the array is swapped in.
• Realistic values via Faker (optional). Install @faker-js/faker and fields named email, name, uuid, createdAt, … plus OpenAPI formats (uuid, email, date-time, uri, ipv4, …) get realistic values. Without it, output falls back to deterministic placeholders.
• Latency + error injection. --latency 200 for a fixed delay, --latency 100-500 for a random range. --error-rate 0.1 returns a randomly-picked declared 4xx/5xx response 10 % of the time.
• Optional persistence. --persist ./fixtures.json writes the in-memory store to disk on every mutation and loads it on restart.

Flags

Programmatic API

Node-only — on PHP use the vendor/bin/doctreen mock CLI, which exposes the same flags.

const { startMockFromOpenApi } = require('doctreen/mock');

const { app, server, routeCount } = await startMockFromOpenApi({
  from: './openapi.json',
  port: 4000,
  latency: [100, 500],
  errorRate: 0.05,
});

// later
server.close();

Schema → example helper

The generator powering the mock server (and the docs UI's Copy-as-cURL / Postman buttons) is exported on its own:

const { generateExample } = require('doctreen/example');

generateExample(
  { type: 'object', properties: { email: { type: 'string', format: 'email' } } },
  { faker: true }
);
// → { email: 'Ada.Lovelace@example.com' }

Accepts both doctreen SchemaNode and OpenAPI Schema Objects. Pass components to resolve $refs.