MirageAPI documentation
Everything you need to turn an OpenAPI spec into a working mock server, in the browser or on your own machine.
Using the web app
- Open the app.
- Upload a spec file, paste its contents, load it from a public URL (GitHub file links work), or click Load demo to try the sample customer/order API.
- Review the validation report for errors, warnings and suggestions about your spec.
- Click Start Server. Every path in your spec is now live on the same domain, for example
https://mirageapi.com/customers. - Pick an endpoint in the explorer and send a request. The controls above the response let you force a status code, add latency, use the spec's examples or turn validation off.
Tip: link straight to a spec with https://mirageapi.com/app/?spec=<url> and it loads when the page opens.
Sharing a mock URL
Click Share in the spec bar to get a public link such as https://mirageapi.com/m/Ab3dE7xY. Anyone — a teammate, a frontend app, a CI job — can call your endpoints under it without a browser session:
curl https://mirageapi.com/m/Ab3dE7xY/customers- Validation, status and latency simulation and examples all work on shared links.
- Edited the spec? Click Update link to publish the changes at the same URL, or Stop sharing to turn it off.
GET /m/<id>/_mirage/routeslists the shared routes.- Links last 7 days and are reset if the MirageAPI server restarts. Each link allows up to 600 requests per minute.
Running the CLI locally
The CLI serves your spec on localhost with no session or browser needed — ideal for frontend development and CI.
git clone https://github.com/venkatbandaru99/mirage.git
cd mirage
yarn install # or: npm install
node src/index.js --spec ./examples/sample-spec.yaml --port 3000On startup the CLI validates the spec, prints every registered endpoint and starts listening:
✓ Spec loaded and validated successfully
Mirage mock server running on http://localhost:3000
📋 Endpoints:
GET /customers
POST /customers
GET /customers/{id}
GET /orders
POST /orders
GET /orders/{id}Options
| Option | Description |
|---|---|
-s, --spec <file> | Path to the OpenAPI spec (JSON or YAML). Required. |
-p, --port <number> | Port to listen on. Default 3000. |
--no-validate | Accept requests that don't match the spec (validation is on by default). |
--quiet | Suppress the startup banner. |
-w, --web | Run the full web app instead (requires yarn build and a SESSION_SECRET environment variable). |
Every request is logged to the console with its timestamp, method and path. CORS is enabled for all origins, so a frontend on another port can call the mock directly.
Supported spec formats
- OpenAPI 3.0 and 3.1, and Swagger/OpenAPI 2.0 (response schemas, examples, body and typed parameters)
- JSON or YAML
- Local
$refreferences between components are resolved automatically
Specs are validated with swagger-parser before any route is registered, so a broken spec fails fast with a clear message.
How data is generated
Responses are generated from the success response schema (200, then 201, then default) using Faker. Each request produces new data.
| Schema | Generated value |
|---|---|
enum | A random value from the list (any type) |
string, format: email | A valid email address |
string, format: uuid | A v4 UUID |
string, format: date / date-time / time | A past date (YYYY-MM-DD), ISO 8601 timestamp, or HH:MM:SS |
string, format: uri / url | A URL |
string, format: phone / password / byte / binary | A phone number, password, base64 string or hex string |
string with minLength/maxLength | Text whose length is within the bounds (default 5–50 characters) |
string with a common field name | A realistic value based on the property name: firstName, lastName, name, username, email, phone, street, city, state, country, postalCode, company, productName, url, currency and more, including suffixes such as billingCity. Names ending in Id get a UUID. Used only when the value also satisfies the field's length and pattern constraints. |
string with pattern | A value generated from the regular expression and checked against it. Complex patterns (lookaheads, backreferences) fall back to a numeric or word value. |
integer / number | A value within minimum/maximum (default 0–1000), honouring exclusiveMinimum, exclusiveMaximum and multipleOf. Numbers are rounded to 2 decimals. |
boolean | true or false |
array | Between minItems and maxItems items (default 1–5), each generated from items |
object | All required properties, plus each optional property about 70% of the time. additionalProperties schemas add a few extra keys. |
allOf / oneOf / anyOf | allOf schemas are merged; for oneOf/anyOf one option is picked at random |
How requests are handled
| Request | Response |
|---|---|
GET, DELETE and other methods | 200 with data generated from the success response schema |
POST, PUT, PATCH with a JSON body | 201 echoing your body, with a generated id and a createdAt timestamp (if not already present) |
POST, PUT, PATCH without a body | 201 with data generated from the 201/200/default schema |
Path parameters such as /customers/{id} | Any value matches the route; the value is then validated against the parameter's schema |
| A request that doesn't match the spec | 400 listing each problem (see request validation) |
| A path not in the spec | 404 with the list of available routes |
Request validation
Requests are checked against the spec before a response is generated: path parameters, query parameters (required, type, enum, format, ranges) and the JSON body. A request that doesn't match gets a 400 listing every problem:
{
"error": "Request validation failed",
"errors": [
{ "in": "body", "path": "/lastName", "message": "must have required property 'lastName'" },
{ "in": "body", "path": "/email", "message": "must match format \"email\"" }
]
}readOnly properties such as a server-generated id are not required in request bodies. To skip validation, send ?__validate=false or the X-Mirage-Validate: false header, untick Validate requests in the app, or start the CLI with --no-validate.
Simulating status codes, latency and examples
Add these to any mock request (in the app, use the controls above the response). Query parameters starting with __ are MirageAPI's own and are never validated against your spec.
| Control | Query parameter | Header |
|---|---|---|
| Force a status code | ?__status=404 | X-Mirage-Status: 404 or Prefer: code=404 |
| Add latency | ?__delay=800 or a random range ?__delay=200-800 (max 10 s) | X-Mirage-Delay: 800 |
| Return the spec's examples | ?__example=true | Prefer: example or X-Mirage-Example: true |
| Skip validation | ?__validate=false | X-Mirage-Validate: false |
A forced status code uses the response your spec defines for that code (its schema or example) when there is one, and a generic { error, status, message } body otherwise; 204 has no body. In example mode the response-level example is returned when present; otherwise property example values are used and anything without one is generated.
Built-in routes
GET /_mirage/health— server status and number of loaded routesGET /_mirage/routes— every mocked route with its method and response codes
Current limitations
- Mocks are stateless: data created with
POSTis not returned by laterGETcalls. - Only JSON request and response bodies are mocked and validated.
- Shared links are kept in memory: they last 7 days and are reset when the server restarts.
Have a feature request? Open an issue on GitHub.