How an OpenAPI Mock Generator Decides What to Return

An OpenAPI spec can describe an endpoint with several possible response codes, and a field that can validly be one of several different shapes. A mock generator has to collapse all of that down to one concrete JSON value per call — there's no way around picking something. Which response, and which shape, it picks isn't random. It's two separate, simple, first-match rules, and knowing them explains a surprising amount of "why does my mock always look like this".

oneOf and anyOf always generate from the first alternative

A schema using oneOf: [Cat, Dog] says a value can validly be either shape. Generating an example from it, though, isn't a 50/50 split or a random pick — it's always the first one listed:

{ "kind": "cat", "meow": true }

{ "id": 1, "name": "string" }

Put Dog first in the schema instead and every mock would be dog-shaped instead — the order in the spec is what decides it, not anything about the data. For a schema with a true discriminated union (say, a webhook payload that's one of six event types), this means a mock server built from it will only ever hand back the first event type, no matter how many times you call it. That's rarely what anyone actually wants when testing — if your frontend needs to handle all six shapes, generating from this schema alone won't exercise five of them.

When an endpoint has multiple possible responses, one specific one wins

Real endpoints document more than one response — a 200 for success, a 404 or 400 for the failure cases, sometimes several of each. The generator has to settle on exactly one response to actually mock, and the rule is: the first response whose status code starts with 2 that also has a schema attached, or, failing that, just the first response with a schema at all, in whatever order the spec lists them. Put a 404 before a 200 in the spec and the mock still comes back as the 200 shape — the rule checks for a leading 2, not document order among the response codes themselves. But an endpoint that documents only error responses (no 2xx at all) will mock whichever error response happens to be listed first, which is easy to miss if you're expecting a success shape and don't notice none was ever defined.

A quiet exception: fields literally named id

Every other field gets either a canned formatted value (an email-format string becomes a realistic-looking email, a date-time becomes an ISO timestamp) or a generic placeholder drawn from a small fixed word pool. A property whose key is literally id (case-insensitive) is the one exception: it gets a readable, sequential value instead — 1, 2, 3 for a numeric id, or id_1, id_2 for a string one. Generate a mock array of ten items and every one gets a distinct, incrementing id rather than ten identical or ten meaningless random-looking values — which matters specifically because ids are the one field a frontend is most likely to use as a React key or a lookup, where duplicates would cause real, confusing bugs in whatever you're testing against the mock.

Composition and circular references are handled, not avoided

allOf merges every listed sub-schema's generated properties into one object, which is how a spec composes a shared base schema with endpoint-specific extensions. And because OpenAPI schemas can reference each other — including, in a self-referential tree structure, themselves — the generator tracks which $refs it has already started resolving in the current path and returns an empty object instead of recursing forever the moment one repeats, rather than hanging the page on a schema that references itself.

Try it yourself

OpenAPI Mock Generator runs both of these rules for real on any spec you paste in — generate a one-off JSON example per endpoint, or export a complete set of MSW request handlers and see exactly which response each one mocks. OpenAPI Validator is worth running first if a generated mock looks wrong — a missing schema or a response with no content at all will produce an empty or unexpected mock without necessarily raising an error of its own. Both run entirely in your browser.