If landscape mapping is where governance starts, OpenAPI is where it lives. It is the center of gravity for everything I do when I govern REST APIs, and the reason is simple and worth saying out loud: OpenAPI is the machine-readable contract, and the contract is the thing you govern. Not the code. Not the running service. The contract. Once you internalize that, the whole rest of the governance stack snaps into place, because everything hangs off the OpenAPI document. Your style guide describes it. Your Spectral rules lint it. Your reviews are reviews of it. Your pipeline gates on it. Your mocks, your SDKs, and your docs are generated from it. The OpenAPI is the artifact the entire program orbits.
The first thing I hold as non-negotiable is that the OpenAPI is the source of truth, not a byproduct. If your spec is generated as an afterthought from code annotations and nobody on the team ever opens it, you are not governing your API, you are governing a description of an API that already shipped. There is a real difference, and we’ll get into design-first versus code-first later in this series. For now, just know that a spec nobody reads is a spec you can’t govern, no matter how clean the YAML looks.
The second thing, and this is the one that surprises people, is that the descriptions and summaries are the battleground. The info.description, the operation summary and description, the parameter descriptions, the schema property descriptions — this is where engineering and product actually negotiate what the API is. I learned to watch the descriptions like a hawk, because the inability or unwillingness of an engineer to describe their operation in one clean sentence correlates almost perfectly with a poorly designed operation. If you can’t say what it does, you probably didn’t design it well. So the cheapest, highest-signal governance rule you will ever ship is “every operation has a meaningful description,” because it forces design debt to the surface before deployment, when it’s still cheap to fix. I’ll say it as plainly as I can: descriptions are the cheapest form of governance there is.
The third thing is that you have tools for the cases where the contract itself isn’t the right home for something. The tone you need for a contract negotiation between engineering and product is not the tone you need for developer-facing documentation, and trying to make the OpenAPI serve both jobs makes it worse at both. This is what OpenAPI Overlays are for — you augment a spec without editing the source. It’s what extensions are for — you carry governance metadata the spec proper has no place to hold. Use them. Don’t overload the contract with everything; let it be the contract and let the other artifacts do the other jobs.
Here is the part that makes all of this more urgent than it was a few years ago. For a long time the consumer of your OpenAPI was a human developer or a code generator. Increasingly, it’s an AI agent, reading your spec to decide how to call you. A weak, under-described, inconsistent OpenAPI was always a liability, but a human would grind through it. An agent won’t. So if your OpenAPI is weak, fix it first, before you do anything else in this series, because it is about to be the input to every other fundamental — your schema governance, your rules, your pipeline, your reviews — and now it’s the thing a machine reads to figure out how to use your business. Govern the contract, and you’ve started governing everything that depends on it.
