@arunapb/openapi-mocker

Instant mock server from any OpenAPI spec — no coding required.

Point mockr at a .yaml or .json OpenAPI file and get a fully working HTTP server with realistic fake responses generated from your schemas, in seconds.

mockr serve api.yaml
# ✓  Mocking 12 routes on http://localhost:4010
#   GET     /users
#   POST    /users
#   GET     /users/:id
#   ...

Features

• Zero config — just pass your spec file
• Realistic fake data — driven by schema types, formats, and field names
• Example-first — uses example values from your spec when present
• Watch mode — auto-reloads the server when the spec file changes
• Simulated latency — add a delay to mimic real network conditions
• CORS enabled — ready for browser-based frontend development
• OpenAPI 3.x support — handles $ref resolution automatically

Installation

npm install -g @arunapb/openapi-mocker

Or run without installing via npx:

npx @arunapb/openapi-mocker serve api.yaml

Usage

Basic

mockr serve <spec>

<spec> is the path to your OpenAPI spec file (.yaml or .json).

Options

| Option | Default | Description | |---|---|---| | -p, --port <number> | 4010 | Port to listen on | | -d, --delay <ms> | 0 | Add simulated response latency (milliseconds) | | --watch | off | Reload the server automatically when the spec file changes |

Examples

# Start on the default port
mockr serve api.yaml

# Custom port
mockr serve api.yaml --port 3000

# Simulate a slow API
mockr serve api.yaml --delay 500

# Watch the spec file and auto-reload on changes
mockr serve api.yaml --watch

# Combine options
mockr serve api.yaml --port 3000 --delay 200 --watch

How responses are generated

For every route in your spec, mockr picks the first 2xx response (falling back to the first response defined) and builds the response body using this priority order:

1. example field on the response schema — used as-is
2. enum — picks a random value from the list
3. Type + format — generates realistic data using Faker.js:

| Format | Generated value | |---|---| | date-time | ISO 8601 datetime string | | date | ISO 8601 date string | | email | Random email address | | uri / url | Random URL | | uuid | Random UUID | | password | Random password | | hostname | Random domain name | | ipv4 | Random IP address |

4. Field name heuristics — when no format is specified, the field name is used to infer appropriate data:

| Field name contains | Generated value | |---|---| | email | Email address | | first | First name | | last | Last name | | name | Full name | | phone | Phone number | | address, city, country, zip, postal | Location data | | url, link | URL | | image, avatar | Image URL | | description, bio | Lorem sentence | | title | Short phrase | | price, amount | Commerce price | | id | UUID |

For number / integer types, minimum and maximum from your schema are respected.

Spec file example

openapi: 3.0.0
info:
  title: Bookstore API
  version: 1.0.0
paths:
  /books:
    get:
      summary: List all books
      responses:
        '200':
          description: A list of books
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
  /books/{id}:
    get:
      summary: Get a book
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single book
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        price:
          type: number
          minimum: 1
          maximum: 100
        email:
          type: string

Running mockr serve bookstore.yaml produces:

GET  /books      → [{ id: "a3f...", title: "lorem ipsum", price: 42.5, email: "[email protected]" }, ...]
GET  /books/:id  → { id: "a3f...", title: "lorem ipsum", price: 42.5, email: "[email protected]" }

How it works

OpenAPI spec file
      │
      ▼
  parseSpec()          — dereferences all $ref entries
      │
      ▼
  extractRoutes()      — builds a list of routes with schemas
      │
      ▼
  createServer()       — registers routes on a Fastify server
      │
      ▼
  generateFromSchema() — produces fake response bodies on each request

Requirements

• Node.js 18+
• An OpenAPI 3.x spec file

Contributing

git clone https://github.com/arunapb/openapi-mocker
cd openapi-mocker
npm install
npm run build

Pull requests are welcome. For major changes please open an issue first.

License

MIT