Prism Mock

Last reviewed Sep 13, 2026 · 806 words

npx @stoplight/prism-cli mock openapi.yaml

That command gives you a working HTTP API on port 4010 that answers every path in your spec with the examples you wrote, rejects requests that violate the schema with a 422, and needs 128 MB of RAM. Prism is not a server you install once and administer; it is a tool you run next to the thing you are building. This guide is about where it sits in a self-hoster's stack, because used well it removes a category of integration bugs, and used badly it convinces you an API works when only its documentation does.

Two modes, and the proxy mode is the underrated one

Mock mode is the famous one: frontends build against an API that does not exist yet, the spec becomes the agreement, and backend work proceeds in parallel. Static mocking returns the first example in the spec for each response; -d (dynamic) generates values that satisfy the schema so lists are not always the same 1 item. Pick responses with a request header: Prefer: code=404 forces an error path, Prefer: example=empty picks a named example. Those two headers are how you test a UI's error states without breaking the backend on purpose.

Proxy mode is what I use more:

prism proxy openapi.yaml https://api.internal.example.com --errors

Prism forwards every request to the real service and validates both the request and the response against the spec. With --errors, a mismatch fails the call instead of just logging. Run your integration test suite through it and you get spec-conformance testing for free: the moment the backend adds a required field or changes a type without updating the document, the tests turn red. For a homelab that exposes a few internal APIs to scripts and dashboards, that is the cheapest possible guard against silent drift.

It runs anywhere, and the Docker image is the way to keep it in a stack

The CLI is Node, so a global npm install -g @stoplight/prism-cli works on any machine. In a compose file the stoplight/prism image slots in as a sidecar:

services:
  mock-api:
    image: stoplight/prism:5
    command: mock -h 0.0.0.0 /specs/openapi.yaml
    volumes:
      - ./openapi.yaml:/specs/openapi.yaml:ro
    ports:
      - "4010:4010"

Bind to 0.0.0.0 inside the container, because the default is localhost and the port mapping will look broken. Mount the spec read-only and Prism reloads when it changes. A team that keeps its OpenAPI file in the repo gets a mock environment in every branch's CI with no further work.

Mock realism is limited, and that is a design choice

Prism has no state. A POST /users returns the example 201 body; a following GET /users does not include the record you just created. There is no scripting layer, no scenario recording, no latency injection beyond what you add in front. That keeps the spec as the only source of truth, which is the point, but it means Prism cannot simulate a stateful workflow. When you need "create then fetch then delete" to behave, Mockoon (with its rules and data buckets) or WireMock (with scenarios and stateful stubs) are the right tools, and both can also import an OpenAPI file to start from. WireMock is the larger project and the safer bet for a team that needs Java-side stubbing in CI.

The other hard requirement is the spec itself. Prism does nothing without an OpenAPI 2 or 3 document, and a sloppy one produces sloppy mocks: missing examples give you empty objects, loose schemas let bad requests through. Time spent tightening required arrays and adding examples is repaid immediately.

Where it fits with the rest of a dev-tools shelf

I keep Prism next to Hoppscotch for manual poking and a spec linter in CI. The workflow is: write or change the spec, lint it, mock it, build the client against the mock, then switch the client's base URL to the proxy in front of the real service and run the same tests. Nothing in that chain requires a SaaS account, which is the whole reason it belongs on a self-hosted dev tools list even though it is not a long-running server.

What I'd do

Add a mock-api sidecar to the compose file of any project that has an OpenAPI document, wire the frontend's dev config to port 4010, and run the integration suite through prism proxy --errors in CI. Stop there. If someone asks for stateful mocks, do not fight Prism into it; reach for WireMock. Prism does one job with almost no operating cost, and its restraint is the reason the spec stays honest.