Scalar Mock Server Skill

Reference for implementing and debugging mock APIs with @scalar/mock-server. Use this when you need realistic API responses from an OpenAPI description document, custom request behavior, seeded data, or Docker-based mock environments.

Overview

Package: @scalar/mock-server
Runtime: Node.js (package engine: >=22)
Main API: createMockServer(options)
Docs:
- Getting started: https://scalar.com/tools/mock-server/getting-started
- Custom request handlers (x-handler): https://scalar.com/tools/mock-server/custom-request-handler
- Data seeding (x-seed): https://scalar.com/tools/mock-server/data-seeding
- Docker: https://scalar.com/tools/mock-server/docker

Quick Start

Fastest way to run a mock server from a local OpenAPI description:

npx @scalar/cli document mock openapi.json --watch

Programmatic setup:

import { serve } from '@hono/node-server'
import { createMockServer } from '@scalar/mock-server'

const app = await createMockServer({
  document: './openapi.yaml',
  onRequest({ context, operation }) {
    console.log(context.req.method, context.req.path, operation.operationId)
  },
})

serve({ fetch: app.fetch, port: 3000 })

`createMockServer()` Options

At least one of the following is required:

document: OpenAPI description document as URL, file path, or object
specification: deprecated alias for document

Optional:

onRequest({ context, operation }): callback before each request is processed
validateRequest: set to false to always return a mock response instead of rejecting contract violations with 422 (default: true)
logger: pass false to silence the authentication instructions printed on startup, or a (line) => void sink to redirect them (default: logs to the console)

Built-in Behavior

When the server starts, it:

Processes and loads the OpenAPI description document.
Seeds schema data from x-seed extensions (idempotent: only when collection is empty).
Registers authentication routes for declared security schemes.
Registers operation routes for each path + method.
Exposes the source document at:
- /openapi.json
- /openapi.yaml

Custom Request Logic with `x-handler`

Use x-handler in an operation for dynamic behavior instead of static examples.

Helpers available in x-handler:

store for in-memory persistence (list, get, create, update, delete, clear)
faker for generated test data
req for request data (body, params, query, headers)
res for response examples by status code (res['200'], res['404'], ...)

Status behavior:

store.get() / store.update() => 200 when found, 404 when not found
store.create() => 201
store.delete() => 204 when deleted, 404 when not found
store.list() => 200
Returning null/undefined triggers 404 (uses responses.404 example/schema when provided)

Seed Data with `x-seed`

Use x-seed on components.schemas.<SchemaName> to seed initial data at startup.

Helpers available in x-seed:

seed.count(n, factory)
seed(array)
seed(factory) (single item shortcut)
faker, store, and schema

Key rule: the schema key name is used as the collection name.

Docker Usage

Run the Docker image:

docker run -p 3000:3000 scalarapi/mock-server --url https://api.example.com/openapi.yaml

Document source priority (high to low):

--url <URL>
OPENAPI_DOCUMENT
OPENAPI_DOCUMENT_URL
/docs volume-mounted files

Useful routes:

Mock endpoints: from your OpenAPI paths
API reference UI: /scalar
Description document: /openapi.json, /openapi.yaml

Troubleshooting Checklist

Confirm the OpenAPI description document is valid and reachable.
Confirm at least one document source is configured (document, --url, env var, or mounted file).
If seeded data is missing, check x-seed exists on schema keys and the collection was empty on startup.
If auth-protected routes return unauthorized responses, verify matching securitySchemes and request credentials.
If custom logic fails, inspect x-handler runtime errors (mock server returns 500 with handler error details).
For an unhandled 500 (one whose error is Internal Server Error), read its operation object — it names the method and OpenAPI path that failed, plus the operationId when the document declares one.

mock-server