OpenAPI Is a Contract, Not Documentation

Ask most engineering teams where their OpenAPI spec comes from, and a common answer is: it's auto-generated from the code, as a side effect of annotations already scattered through the route handlers, mostly so a Swagger UI page exists somewhere. That's a completely reasonable thing to want. It's also a sign the spec is being treated as documentation of what the backend happens to do, rather than as a contract of what it's supposed to do — and that distinction has real consequences.
Documentation describes. A contract constrains.
Documentation generated from code can only ever describe the code's current behavior, correct or not. If a bug causes an endpoint to return id as a string when it's supposed to be a number, code-generated docs will faithfully document the bug, because that's genuinely what the code does right now.
A contract is different: it's an assertion about what should happen, written independently of any one implementation, that both a client and a server can be checked against. When the spec is the source of truth and the implementation is generated or validated from it — rather than the other way around — a mismatch between what the backend actually returns and what it promised to return becomes a bug to fix, not an accident to silently document.
This is the same distinction as a database schema versus a data dump: a dump tells you what's there now; a schema tells you what's allowed to be there, and rejects anything that isn't.
Where teams actually feel this
A few concrete places where "spec as contract" pays off compared to "spec as generated documentation":
- Client generation. A spec-first API can have its client SDKs generated automatically for every language a team uses, and regenerated the moment the spec changes — which only works cleanly if the spec is authoritative and stable, not a snapshot of whatever the backend happened to do at generation time.
- Contract testing. Tools that validate real request/response pairs against an OpenAPI schema can catch a backend silently breaking its own contract — returning an extra required field as optional, changing an enum's allowed values — in CI, before a client ever sees it in production.
- Mocking before the backend exists, which only works well if the spec was written (or agreed on) before the implementation, rather than extracted after it.
- Onboarding. A new engineer reading a deliberately-written spec learns the intended shape of the API. One reading auto-generated docs learns whatever the current implementation happens to do, bugs and all, with no signal about which parts are intentional.
The practical middle ground
Very few teams write a perfect spec-first workflow from day one, and that's fine — the useful habit isn't "write OpenAPI by hand in a text editor before any code exists," it's treating whatever spec you have as a thing you actively maintain and trust, not a byproduct you regenerate and forget.
A few habits that get you most of the value without a total process rewrite:
- Keep the spec versioned alongside the code, not generated fresh on every deploy from whatever annotations exist that day, so a diff on the spec is a reviewable, meaningful change.
- Use it to generate a mock, not just a docs page. A spec that only ever produces a static Swagger UI page is easy to let drift, because nothing breaks when it does. A spec that also generates a live mock other people's code actually calls creates immediate pressure to keep it accurate — if the mock and the real API disagree, someone notices fast.
- Export what you've mocked back into a spec, when you've built something against a mock first and the "spec" so far only exists as a set of configured routes. That gives you a real, shareable OpenAPI document to hand to the backend team as the actual target, instead of a verbal description of what you expect.
MockBase supports both directions of this: importing a spec turns it into working routes so you can build against a contract immediately, and exporting a mock turns your configured routes back into a spec document — useful when the mock came first and you need to hand the agreed contract to whoever's building the real implementation.
Whichever direction you go, the underlying point is the same: a spec earns the word "contract" by being something people are held to, not something that's regenerated to match whatever already shipped.
Xerat02
Building MockBase.
More from the blog

Consumer-Driven Contract Testing, Explained Without the Buzzwords
Instead of an API's team guessing what's safe to change, consumers write down exactly what they depend on — and the API gets tested against that, not against a vague sense of "probably fine."

When Your Mock Lies to You: The Contract Drift Problem
Mocking a dependency is a productivity win right up until the mock quietly stops matching reality — at which point it's worse than not having one, because it gives you false confidence.