Quick Answer
An OpenAPI mock server generates live HTTP endpoints from your Swagger/OpenAPI spec. For each operation in the spec, it serves the example or schema-generated response at the documented path. Top tools: Prism (CLI), Stoplight (SaaS), Microcks (self-hosted), and hosted platforms like Requex.me. Prism is the quickest start if you want a local mock; hosted tools win when your team or CI needs shared access.
OpenAPI Mock Server — Your Spec Becomes a Live API
An OpenAPI-driven mock closes the gap between "API contract agreed" and "frontend can build." The spec is the source of truth; the mock is a live consumable version of it. This guide covers the tool landscape, setup steps, and the tradeoffs between each approach.
What Makes a Mock "OpenAPI-Driven"
The mock reads your openapi.yaml (or .json) and for every path + method combination:
- Matches incoming requests to the operation
- Returns the documented response — using
examplesfirst, thenexample, then generated fromschema - Validates incoming request bodies and query params against the spec
- Returns 4xx when the request violates the contract
The net effect: your frontend can work against a realistic API that will match the real backend's shape, and your spec automatically stays honest.
Tool Landscape
| Tool | Type | Strength | Weakness |
|---|---|---|---|
| Prism | CLI | Fast, local, free, validates requests | Localhost only |
| Stoplight Platform | SaaS | Hosted URL, integrates with spec editor | Paid tiers from $99/mo |
| Microcks | Self-hosted | Full-featured, supports AsyncAPI + Postman | Docker/K8s setup required |
| WireMock Cloud | SaaS | OpenAPI import, robust matching | $49+/mo |
| Postman | SaaS | Familiar UI, generates mock from spec | Collection-centric, free tier limits |
| Requex.me | Hosted | Free, OpenAPI import, auth simulation, conditional responses | No record-replay |
Quick Start with Prism (Local)
# install npm install -g @stoplight/prism-cli # mock from a local spec prism mock ./openapi.yaml # → http://127.0.0.1:4010 # mock from a URL prism mock https://example.com/openapi.yaml # add request validation (will 422 on invalid request) prism mock ./openapi.yaml --errors
Prism reads operations, generates responses from examples → schema, and serves them. Add --dynamic to randomize values on each call.
When Local (Prism) Is Not Enough
- CI jobs need to hit the mock — running Prism in every job adds runtime
- Frontend and backend teams need the same URL
- Mobile simulators need a reachable URL, not localhost
- You want to share the mock with an external partner evaluating your API
- You need HTTPS (browser mixed-content blocks HTTP from HTTPS origins)
At this point you move to a hosted option. Stoplight, WireMock Cloud, and Microcks (self-hosted) all solve it. Requex.me covers the hosted case for free with the features most teams need.
Design Tips for Better Mocks
- Write
examples, not just schemas. Generated mocks from schema are technically valid but often nonsensical ("name": "string"). Good examples make the mock useful. - Document error responses in the spec. The 401, 404, 422, 429 responses should exist in the spec so the mock can serve them conditionally.
- Keep one canonical spec file. Avoid forking it into "docs spec" and "mock spec" — they drift fast.
- Validate requests. Return 422 when the mock sees an invalid request body — that catches bugs early.
- Pin the mock URL in CI. Use an env var so you can swap between mock and real without code changes.
FAQ
Does Requex support OpenAPI import?
Yes. Open a mock server, click "Import OpenAPI" in the top bar, and paste or upload an OpenAPI 3.x (or Swagger 2.0) spec in JSON or YAML. Requex creates one mock route per path × method and generates a 2xx response body from examples, example, or schema in that order. Duplicates are skipped, so re-importing after spec changes only adds new routes.
What about AsyncAPI for event-driven mocks?
AsyncAPI covers message-based APIs (Kafka, MQTT). Microcks is the main tool that supports both OpenAPI and AsyncAPI mocking. Requex focuses on HTTP, which pairs with the webhook-testing side of the platform.
Can I mock an auth-protected API?
Yes, with a hosted tool. Requex mock servers support Bearer, HMAC, API key, and Basic auth out of the box. Prism can simulate auth via request validation rules.
How do I handle dynamic IDs in responses?
Requex supports template variables: reference {{params.id}} in the response body to echo the URL param back. Prism with --dynamic generates fresh UUIDs per request.