Write the OpenAPI first, add realistic examples to every schema and response, then point a mock server at it. Prism, Postman, and most API platforms will do this from the document with no additional work. Some tooling can generate plausible responses straight from the schema, but hand-written examples are far better — they surface disagreements about what the data actually looks like.
The value is not the mock. The value is that a contract nobody can run is an abstraction people nod at, and a mock they can call is something they will argue with. Front-end developers start building against it. Partners tell you the field they actually need. Someone notices that the flow requires three calls where it should require one. All of that feedback arrives while it is still free to act on.
Keep the mock honest as you go: mock the error responses and the rate-limit response too, not just the 200s. Consumers who only ever saw the happy path will discover your error format in production.
And retire the mock deliberately once the real thing exists, or make the switch a configuration change. Long-lived stale mocks quietly become a second, wrong source of truth.
