Last updated:
OpenAPI Mock Server Generator
Turn a spec into a mock server you run yourself, made in your browser.
How to use the mock server generator
Paste a Swagger 2.0 or OpenAPI 3.x spec, in YAML or JSON, open a spec file, or load a sample: three versions of a small pet store, or the spec of our own fake REST API. The spec is checked against the official schema for its version, then every operation gets an example response for each status code it documents. Open an operation to see them, each marked as taken from the spec's examples or generated from its schema.
Then take the mock server you want: a Mock Service Worker handlers file, a json-server database and routes, the Prism commands, or a Postman collection. Each is made in your browser from the same example responses, so they agree with each other and with the page. Nothing is uploaded, which is also why there's no hosted mock address: the mock runs where your code runs.
Which mock server to use
| Runs | Best for | Needs | |
|---|---|---|---|
| Mock Service Worker | Inside your app or tests, by intercepting requests | Front-end tests and local development with no server at all | The msw package (2.x or 3.x) |
| json-server | A local HTTP server on port 3000 | Lists you can add to and change while you click through a prototype | Node.js; the spec's list endpoints |
| Prism | A local HTTP server on port 4010 | A mock that follows the spec closely, including request validation | Node.js and the spec file |
| Postman | In the Postman app | Trying each request by hand with the documented responses beside it | Postman |
Mock Service Worker handlers
The handlers file exports three things: BASE_URL, the spec's first server address (change it to whatever your app calls); responses, every documented response body by operation and status; and handlers, one per operation, answering with its lowest 2xx response. A {petId} in a path becomes MSW's :petId, and a response without a body, such as a 204, is answered with an empty body. It imports http and HttpResponse from msw, which both MSW 2 and MSW 3 export; our tests type-check a generated file against each version and run its handlers.
// vitest.setup.ts (or jest.setup.ts)
import { setupServer } from "msw/node";
import { afterAll, afterEach, beforeAll } from "vitest";
import { handlers } from "./handlers";
export const server = setupServer(...handlers);
beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close()); To test another case, such as a 404, swap one handler for a test with server.use() and the matching entry of responses:
import { http, HttpResponse } from "msw";
import { BASE_URL, responses } from "./handlers";
import { server } from "./vitest.setup";
test("shows the not-found message", async () => {
server.use(
http.get(`${BASE_URL}/pets/:petId`, () =>
HttpResponse.json(responses["GET /pets/{petId}"]["404"], { status: 404 }),
),
);
// ...render the page and assert on what it shows
});
In a browser, use setupWorker(...handlers) from msw/browser instead, after copying MSW's worker script into your public folder with npx msw init ./public (use your project's public folder). In Node, MSW needs an absolute BASE_URL.
json-server
Each GET endpoint without path parameters that returns JSON becomes an entry in db.json: a list of objects becomes a collection, and an object becomes a single resource. Every record in a collection gets a unique id, because json-server finds records by it, so an item path such as /pets/{petId} is served from the pets collection. routes.json maps the spec's base path, such as /v1, and nested paths such as /store/inventory onto those entries. Paths with other parameters aren't in db.json.
npx json-server@0.17.4 --watch db.json --routes routes.json
The routes file needs json-server 0.17.4, its last stable release; the 1.0 releases are still betas and dropped custom routes. A plain npx json-server db.json installs the beta, which serves the same collections without the base path. Unlike the other mocks, json-server saves the changes you POST, PUT, PATCH or DELETE into db.json, so keep a copy of the downloaded file.
Prism
Prism, from Stoplight, reads the spec itself, so it needs only the spec file and these commands. It serves the spec's examples by default, or with -d generates a response from each schema on every request, and it checks each request against the spec as well. Ask for a documented response other than the first 2xx with a Prefer header. Prism reads Swagger 2.0, OpenAPI 3.0 and 3.1.
npx @stoplight/prism-cli mock openapi.yaml
curl http://127.0.0.1:4010/pets/1
curl -H "Prefer: code=404" http://127.0.0.1:4010/pets/1 Postman collection
The collection follows Postman's Collection Format v2.1.0, and our tests validate every generated collection against its published JSON Schema. Each operation is a request in a folder named after its first tag, with path parameters filled in from the spec's examples where it has them, and a request body when the operation takes one. Every documented response is saved with it as an example, with its status code, content type and body. The baseUrl variable holds the spec's first server, or Prism's address, http://127.0.0.1:4010, when the spec names none. Bring it into Postman with its Import button.
Good examples make good mocks
A generated body matches its schema, but only a written example says what a real response looks like: names that read like names, ids your app expects, a realistic error. Write an example for the responses your front end depends on most, and let the schemas cover the rest. Required properties, formats such as email and date-time, enums, patterns and minimum and maximum values all make generated bodies more useful. In OpenAPI 3.0 a nullable field may be generated with or without a value, a readOnly property is left out of request bodies and a writeOnly one out of responses.
Before you mock a spec, check it with the OpenAPI Validator: this page shows the number of errors and links there. To see how an API's real responses compare with the spec, its second tab checks a response against an operation. For the data in a single schema, without a whole API around it, the Mock Data Generator makes up to 1,000 records as JSON or CSV.
FAQ
Is my spec uploaded to a server?
No. The spec is parsed, checked and turned into mocks in your browser, and the exports are made there too and saved by your browser as downloads. We record what kind of run it was: the spec's version, its counts of operations and responses, how many came from examples, the numbers of errors and their codes, and which export you took, never the spec or a response. See the privacy policy.
Why doesn't it give me a hosted mock URL?
Hosting a mock of your spec would mean uploading the spec to our server and keeping it there, and nothing you paste into these tools leaves your browser. Run the mock where your code runs instead: Mock Service Worker inside your tests or app, json-server or Prism on your machine. For a public API with generic data to point a tutorial or a prototype at, use the free fake REST API.
Which spec versions does it read?
Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2, in YAML or JSON. It checks the spec with the OpenAPI Validator's engine first and says how many errors it found; mocks are still made from a spec with errors, but they can only be as right as the spec.
Where do the example responses come from?
From the spec when it has them: a media type's example, the first of its examples, Swagger 2.0's examples for application/json, or an example on the schema. Otherwise the body is generated from the response schema by the Mock Data Generator's engine, with a fixed seed, so the same spec always gives the same mocks. Each response on the page says which it is.
What doesn't it mock?
$refs to other files or URLs aren't fetched, so their schemas can't be used; bundle a multi-file spec into one first. Webhooks and callbacks aren't mocked, a body that isn't JSON is answered as text, and an operation with a method MSW has no handler for, such as TRACE, gets a comment in the handlers file instead.
Related tools
- Free fake REST API: a public API with users, posts, products and orders to point a prototype at, no setup needed.
- OpenAPI Editor: write the spec, with a live documentation preview.
- OpenAPI Validator: check a spec against the official schema, and a response against a spec.
- Mock Data Generator: fake records from one JSON Schema.
- Breaking Change Detector: compare two versions of a spec before you update the mocks.