Mocking an API from an OpenAPI Contract

Writing a mock by hand is quick once and expensive afterwards, because the contract keeps moving and the handwritten copy does not. Deriving the mock from the contract removes the copy, which removes the thing that drifts.

What a generator can read

An OpenAPI document carries more mechanical detail than most people use, and a mock generator uses almost all of it.

The paths and methods become the rules. Each operation is one route the mock will answer, with the path parameters left in place so /orders/{orderId} matches any id.

The documented status codes decide what a rule returns. An operation usually declares a success and several failures, and the generator needs one of them as the default, which is nearly always the lowest success code.

The response schema becomes the body. Every property is walked, and each one gets a value from its type and its format, so an integer produces a number and a string with format: date-time produces a timestamp. Required fields are present and optional ones may or may not be.

The field names decide how plausible those values look. A generator that only reads types fills every string with the same placeholder, while one that also reads names produces an address for email and a city for city. That difference is the subject of mock data.

What it cannot know

Everything a generator leaves out has the same cause, which is that a document describes operations one at a time.

Which response is the normal one. An operation with a 200, a 404 and a 409 documented gives no hint about which of them a caller should expect on a Tuesday. The generator picks the success, and the other two need conditional responses to appear at all.

What connects two calls. The order you just created should be in the next list response, and the token from the login should be accepted by the next request. Nothing in a specification states that, so a generated mock answers both calls correctly and inconsistently.

What makes something fail. The document says a 422 exists and describes its body. It does not say that the quantity has to exceed stock, so the failure never fires on its own.

Anything about time or scale. A generated response arrives instantly and contains as many items as the generator felt like producing. Real latency and a list long enough to break a layout are configuration rather than derivation.

The generated mock reports on your schemas

There is a useful side effect here that is worth naming, because it turns an annoyance into a signal.

An operation whose response schema is a typed object produces a body full of plausible values. An operation whose response is declared as a bare object with no properties produces {}, and one with no response schema at all produces nothing worth sending. The mock is not being unhelpful, it is showing you exactly how much of your contract is actually described.

That makes a first generation run a cheap audit. Generate everything, call each route once, and the empty bodies are a list of the schemas that need work before anyone downstream can rely on them.

Coverage is the number to watch

A mock with rules for most of your API is more dangerous than one with rules for none of it, because the gaps are invisible until somebody hits one.

An uncovered endpoint returns a 404, and a 404 from a mock looks exactly like a mistake in the caller's URL. The consumer team loses an afternoon to a path that was simply never generated, usually after the specification grew an endpoint and nobody re-ran the generation.

So the measure to keep in front of you is the share of endpoints in the current version of the contract that an active rule answers. When that number drops, the reason is almost always that the contract moved, which makes it an early warning rather than a score.

In Routebase

A mock server can be created straight from a specification, and the generation runs again whenever the contract grows.

The Generate Mock Rules dialog takes a specification, an optional version filter and a switch that skips endpoints which already have a rule. Re-running it after the contract grows adds the new routes and leaves your edits alone. Generated bodies are built with Smart Mock, which maps each schema field to a generator by name and type rather than filling every string with the same value.

Analytics keeps coverage in view with the uncovered endpoints listed by method and path, and Generate Missing Rules closes the gap without a second pass over the whole specification. The same measure feeds the mock coverage bar on the project dashboard. The Mock Server guide covers generation and coverage, and Schemas covers the structures the bodies are built from.