@tomi_tom/mocksmith

mocksmith

Turn real JSON responses into a JSON Schema, TypeScript types and a runnable mock API — no OpenAPI spec required.

Every mock tool (Prism, Mockoon, openapi-mock, Scalar…) starts from an OpenAPI/Swagger spec. But in real life you usually have the responses first and no spec at all. mocksmith works the other way around: point it at example JSON and it infers the schema, emits types, and serves a mock.

# infer a JSON Schema from real responses
npx mocksmith users.json --array

# get TypeScript types
npx mocksmith users.json --array --types --name User

# emit an OpenAPI 3.1 document
npx mocksmith users.json --array --openapi

# run a local mock server
npx mocksmith serve users.json --array --route /users

# pipe JSON straight from an endpoint — no file needed
curl -s https://api.example.com/users | npx mocksmith --array

Why mocksmith

• No spec needed — infer everything from example responses you already have.
• Three outputs from one input — JSON Schema · TypeScript types · OpenAPI 3.1.
• Smart inference — merges many samples, marks fields optional when they're missing from some, widens integer+number, detects string formats (email, date-time, date, uuid, uri), and unifies disagreeing shapes with anyOf.
• Runnable mock in one command — serve the real example, or --mock for schema-generated data.
• Local & private — no network, no account, zero runtime dependencies.

Inference at a glance

Given users.json:

[
  { "id": 1, "email": "ada@example.com", "active": true, "tags": ["x"] },
  { "id": 2, "email": "lin@example.com", "active": false }
]

mocksmith users.json --array --types produces:

export type ApiResponse = {
  id: number;
  email: string;     // inferred format: email
  active: boolean;
  tags?: string[];   // optional — absent from the second sample
};

Input

• Each file is one sample. Pass several files to merge them.
• With no file argument, mocksmith reads JSON from stdin — so you can pipe an endpoint straight in (curl ... | mocksmith).
• --array treats a top-level array as a list of samples (the common case for list endpoints).
• Output is pipe-aware: ANSI colors are only used when writing to an interactive terminal.
• Missing files and invalid JSON produce a clear one-line message, not a raw stack trace.

Commands & flags

Develop

pnpm install
pnpm test        # vitest — inference, emitters, server, generator
pnpm typecheck
pnpm build       # → dist/

The inference engine (src/infer.ts), emitters, server matcher and data generator are pure functions, fully unit-tested.

Free vs Pro

• Free — inference, JSON Schema / TS / OpenAPI output, mock server, schema-generated data.
• Pro (planned) — record responses straight from a live endpoint, request-body validation against the inferred schema, named nested interfaces, watch mode, and a hosted mock.

License

MIT