Prism Mock Server — A Field Guide

Prism is a CLI from Stoplight that reads an OpenAPI (or Postman) spec and turns it into a running HTTP server — no backend code, no hand-written fixtures. Point it at a spec and it generates responses that match your schemas, using your documented examples where you've provided them and synthesizing plausible values from the JSON Schema where you haven't. The value isn't the mock server itself; it's that the spec becomes the single source of truth two teams can build against independently, instead of one waiting on the other.

What Prism actually does

Give Prism a spec file and one command starts a server that implements it:

npx @stoplight/prism-cli mock ./openapi.yaml --port 4010 --dynamic

Every path and method in the spec is now a real endpoint. Hit GET /orders/123 and Prism finds the matching operation, picks a response for the requested status code, and returns a body shaped exactly like the schema says. Without --dynamic it returns the static examples you wrote in the spec verbatim — useful when you want deterministic fixtures for a specific test. With --dynamic, it generates new values from the schema on every request (a string stays a string, an enum picks one of the listed values, a number respects min/max), which is closer to what a real backend under load actually looks like.

paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Order found
          content:
            application/json:
              schema:
                type: object
                required: [id, status, total]
                properties:
                  id: { type: string, example: "ord_9F2" }
                  status: { type: string, enum: [pending, shipped, delivered] }
                  total: { type: number, format: float, example: 42.5 }
        '404':
          description: Order not found

Why frontend teams reach for it

The obvious use case is building a UI against an API contract before the backend exists. Instead of a shared "the backend team says it'll look roughly like this" Slack thread, the spec is checked into the repo, Prism serves it, and the frontend points its API client at localhost:4010. When the real backend ships, you swap the base URL — the request shapes don't change because the frontend was never coupled to a hand-rolled mock that drifted from what the API actually became. It also means edge cases (404s, validation errors, empty arrays) are testable on day one, because they're just other response entries in the same spec.

The other mode: proxy and validation

Mocking is half of what Prism does. The other half is prism proxy, which sits in front of a real API and forwards every request to it — but validates both the request and the response against the OpenAPI spec on the way through, flagging anything that doesn't match:

npx @stoplight/prism-cli proxy ./openapi.yaml https://api.internal.example.com --errors

This is the mode that catches spec drift. A backend team ships a field rename or drops a required property, the spec doesn't get updated, and normally nobody notices until a consumer's parser breaks in production. Run the real API traffic through prism proxy --errors in a staging environment and it fails loudly the moment a response stops matching its own documentation.

Wiring it into CI

The practical payoff is running prism proxy against a staging deployment as a CI step after every deploy, pointed at the same OpenAPI file that's supposed to describe the service. If the deploy introduced an undocumented breaking change, the step fails before it reaches consumers instead of after a downstream team's integration silently starts erroring. Combined with the mock mode for local frontend development, the spec stops being documentation you write after the fact and becomes the thing both sides of an integration are actually built and checked against.

Wrapping up

Prism's real trick is treating the OpenAPI spec as executable rather than descriptive. Mock mode lets a frontend team build against an API that doesn't exist yet; proxy mode lets you verify that an API which does exist still matches what it claims to be. Neither replaces real integration testing, but both catch a category of "the docs lied" bug that would otherwise surface as a confused bug report from whoever consumes the API last.