How to mock an API from an OpenAPI spec

Updated September 30, 2026

You have an OpenAPI spec, but the real API isn't ready — or you can't reach it from your dev environment. Here's how to get every endpoint responding with realistic data in under a minute.

What you need

• An OpenAPI 3.x or Swagger 2.0 spec in JSON or YAML. No spec yet? Use the sample customer/order spec.
• A browser — or Node.js 18+ if you want to run it locally.

Option 1: In the browser (no install)

1. Open the MirageAPI app.
2. Drag your spec onto the upload area, click Browse, Paste it in, or load it from a public URL. Click Load demo to use the sample spec.
3. Check the validation panel. It lists errors, warnings and suggestions for your spec.
4. Click Start Server.
5. Select an endpoint such as GET /customers and send the request. Send it again — you get different data every time.
6. Click Share to get a public URL like https://mirageapi.com/m/Ab3dE7xY that teammates, apps and CI jobs can call.

Option 2: Locally with the CLI

Running locally keeps your spec on your machine and gives you a stable localhost URL that any tool can call.

git clone https://github.com/venkatbandaru99/mirage.git
cd mirage
yarn install

node src/index.js --spec ./path/to/openapi.yaml --port 3000

Now call it like the real thing:

$ curl http://localhost:3000/customers/123e4567-e89b-12d3-a456-426614174000
{
  "id": "841d15c0-57d1-4083-a085-ca4b6f69e75f",
  …
  "email": "Newton_Hessel@hotmail.com",
  "age": 42,
  "status": "active",
  "createdAt": "2025-12-27T11:24:39.703Z"
}

The id is a UUID because the spec says format: uuid, age is between 18 and 80 because of minimum/maximum, and status is one of the spec's enum values.

Requests are validated too: /customers/123 gets a 400 because 123 isn't a UUID. Add ?__validate=false to skip that.

Testing error cases

Force any status code or add latency to see how your client copes:

curl -i "http://localhost:3000/customers?__status=500"
curl "http://localhost:3000/customers?__delay=2000"
curl -H "Prefer: code=404" http://localhost:3000/customers/123e4567-e89b-12d3-a456-426614174000

Creating resources

POST, PUT and PATCH requests echo your JSON body back with a generated id, so create flows work end to end:

$ curl -X POST http://localhost:3000/customers \
    -H 'Content-Type: application/json' \
    -d '{"firstName":"Ada","lastName":"Lovelace","email":"ada@example.com"}'

{"firstName":"Ada","lastName":"Lovelace","email":"ada@example.com",
 "id":"5cf56f6c-ff5e-4906-9af9-980ce4c3a750","createdAt":"2026-09-29T20:41:15.148Z"}

Tips for more realistic mocks

• Add format to strings (email, uuid, date-time, uri) — it's the biggest single improvement.
• Use enum for status fields so your UI sees every state.
• Set minimum/maximum on numbers and minItems/maxItems on arrays to keep values believable.
• Mark fields as required — optional fields are sometimes left out, which is great for testing how your UI handles missing data.

See the full list of generation rules in the docs.