Prism Mock Server: Generate Mock APIs from OpenAPI Specs

Frontend team waiting on backend APIs to be built. Backend team waiting on the frontend to tell them if the API shape is right. Everyone blocked on everyone else.

Prism breaks this cycle. Give it an OpenAPI spec and it spins up a fully functional mock server — returns realistic example data, validates incoming requests against the spec, and lets both sides work in parallel from day one.

What Prism Does

Prism is an HTTP mock server and proxy that reads OpenAPI specs. In mock mode, it:

• Generates realistic responses from the examples in your spec (or synthesizes them from schemas)
• Validates incoming requests — returns 422 if a request doesn't match the spec
• Handles path parameters, query parameters, authentication schemes
• Supports multiple response scenarios via Prefer headers
• Runs as a CLI, Docker container, or Node.js library

In proxy mode, it sits between your client and a real server, validating both requests and responses against the spec — useful for catching drift in production APIs.

Installation and Quick Start

npm install -g @stoplight/prism-cli

Point it at a spec:

prism mock openapi.yaml

Or a remote spec:

prism mock https://api.example.com/openapi.json

Output:

[CLI] ℹ  info      Server listening at http://127.0.0.1:4010
[CLI] ▶  start     Prism is listening on http://127.0.0.1:4010

Your mock API is live. Every endpoint defined in the spec responds immediately.

Defining Examples in Your Spec

Prism uses the examples sections of your spec to return realistic data:

paths:
  /users/{id}:
    get:
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                alice:
                  value:
                    id: 1
                    name: "Alice Chen"
                    email: "alice@example.com"
                    role: "admin"
                    createdAt: "2024-01-15T10:30:00Z"
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                notFound:
                  value:
                    code: "USER_NOT_FOUND"
                    message: "No user found with the given ID"

components:
  schemas:
    User:
      type: object
      required: [id, name, email, role, createdAt]
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, member, viewer]
        createdAt:
          type: string
          format: date-time

With this spec, GET /users/1 returns the Alice example. If you haven't defined examples, Prism generates synthetic data from the schema.

Multiple Response Scenarios

Use the Prefer header to select different responses:

# Get the default (first) example
curl http://localhost:4010/users/1

# Request a 404 response
curl -H "Prefer: code=404" http://localhost:4010/users/999

# Request a specific named example
curl -H "Prefer: example=alice" http://localhost:4010/users/1

This lets frontend developers test every state their UI needs to handle without a real backend — empty states, error states, loading states, success states.

Request Validation

When a request doesn't match the spec, Prism rejects it:

# Missing required body field
curl -X POST http://localhost:4010/users \
  -H "Content-Type: application/json" \
  -d '{"email": "not-an-email"}'

Response:

{
  "type": "https://stoplight.io/prism/errors#UNPROCESSABLE_ENTITY",
  "title": "Invalid request body payload",
  "status": 422,
  "detail": "Your request body is not valid: ...",
  "validation": [
    {
      "location": ["body", "name"],
      "severity": "Error",
      "code": "required",
      "message": "must have required property 'name'"
    },
    {
      "location": ["body", "email"],
      "severity": "Error",
      "code": "format",
      "message": "must match format \"email\""
    }
  ]
}

Frontend developers get immediate, spec-accurate error feedback — the same error format their real API will return.

Contract-First Development Workflow

The power of Prism is enabling contract-first development. The sequence:

1. Design the API in the spec (before writing any code)

Product, frontend, and backend agree on the shape. Write it in OpenAPI. No code yet.

2. Start the mock server

prism mock openapi.yaml

3. Frontend builds against the mock

Update the base URL in your dev config:

// config/development.js
module.exports = {
  apiBaseUrl: 'http://localhost:4010'
};

Frontend team builds the full UI against realistic mock data immediately.

4. Backend builds against the spec

Backend implements the endpoints knowing exactly what shape they need to produce. No guessing what the frontend needs.

5. Integration testing

Switch the frontend's base URL to the real backend. If both sides followed the spec, it works.

6. Catch regressions with proxy mode

prism proxy openapi.yaml https://api.staging.example.com

All requests flow through Prism to staging. Any response that doesn't match the spec is flagged.

Using Prism in CI Tests

Run Prism as part of your test suite to validate contract compliance:

# .github/workflows/contract-tests.yml
name: Contract Tests

on: [push, pull_request]

jobs:
  contract-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Start Prism mock server
        run: |
          npx @stoplight/prism-cli mock openapi.yaml &
          npx wait-on http://localhost:4010

      - name: Run frontend tests against mock
        run: npm test
        env:
          API_BASE_URL: http://localhost:4010

Your frontend tests run against the mock. If the spec changes in a way that breaks the tests, CI fails.

Dynamic Responses with Callbacks

For more complex scenarios, use Prism's callback support or pair it with a custom server. But for most use cases, the Prefer header approach covers what you need.

You can also set up multiple Prism instances on different ports to simulate multiple services:

# Terminal 1
prism mock user-service-openapi.yaml --port 4010

# Terminal 2  
prism mock order-service-openapi.yaml --port 4011

# Terminal 3
prism mock notification-service-openapi.yaml --port 4012

Your local dev environment now has all three services running — no backend setup needed.

Prism as a Proxy for Validation

In proxy mode, Prism validates real traffic:

prism proxy openapi.yaml https://api.example.com --port 4010

Point your client at localhost:4010 instead of api.example.com. Every request and response is validated. Violations appear in Prism's logs:

[CLI] ✖  error     Request violated the spec: body.price must be number
[CLI] ✖  error     Response violated the spec: missing required property 'currency'

This is invaluable when onboarding new developers — they get spec violations explained rather than cryptic errors from the real server.

Combining Prism with Other Tools

Prism excels as one piece of a larger testing setup:

• Schemathesis generates property-based tests against the mock to find spec inconsistencies
• Newman/Postman runs integration test collections against the mock in CI
• Cypress/Playwright can point at the mock for end-to-end UI tests that don't need a real backend

The OpenAPI spec becomes the hub — Prism serves it as a mock, Schemathesis tests against it, express-openapi-validator enforces it at runtime.

Keeping the Spec Current

The risk with any mock-first workflow: the spec drifts from the real implementation. As the backend evolves, update the spec first. If you're using express-openapi-validator or similar middleware, the real server will reject responses that don't match — giving you an automated check that spec and implementation stay aligned.

Once you're in production, HelpMeTest provides 24/7 monitoring that runs real test scenarios against your deployed API — verifying that what you built matches what your spec promised, continuously, not just at deploy time.