The API docs your OpenAPI spec cannot generate
A generated reference answers what an endpoint accepts. It never answers which endpoint to call, in what order, or what to do when one fails. That part is yours.
Generate a reference from an OpenAPI spec and you get something genuinely useful: every endpoint, every parameter, every response shape, always current. It is the part of documentation that is expensive to hand-write and impossible to keep accurate by hand.
It is also the part that answers the smallest question.
A developer arriving at your API does not open the docs asking what fields POST /subscriptions accepts. They open it asking whether they need a customer before they need a payment method, what happens when the card declines on the third invoice, and whether they should poll or wait for a webhook. Your reference answers none of that, because none of it is in your spec.
The reference tells you what. The guides tell you when.
A generated reference is a dictionary. It is exhaustive and alphabetical and it assumes you already know which word you are looking for.
Nobody integrates an API from a dictionary. They integrate it from a sequence: do this, then this, and here is what goes wrong in between. That sequence lives nowhere in OpenAPI, because OpenAPI describes operations independently. It has no vocabulary for "call this one first".
So the split is not reference-and-then-some-extra-prose. It is two different documents doing two different jobs, and only one of them can be generated.
What has to be written
The order of operations. Any resource that depends on another has an implied sequence, and your spec does not state it. Create the customer, attach the payment method, then create the subscription. A developer can derive that from three schemas if they read carefully and guess correctly. Most will guess wrong once and then read.
Authentication end to end. Your spec declares a security scheme. It does not say where the key comes from, whether test and live keys are different strings, what scopes exist, how rotation works, or which endpoints need elevated credentials. The scheme is a lock; developers need the part about getting a key.
What your errors mean. A generated reference lists status codes. It does not say which of your 400s are retryable, which mean "you sent it twice and we ignored the second", or which will resolve on their own in a minute. This is the single most common gap, and it is the one that generates support tickets, because a developer who cannot tell a transient failure from a permanent one either retries forever or gives up immediately.
Rate limits and quotas. The numbers, the window, the headers you return, and what a client should do when it hits one. Almost nobody puts this in the spec. Almost every integration eventually needs it.
Webhooks as a whole system. Not just the payload schema. How to verify a signature, what your retry schedule is, whether delivery is ordered, whether it is at-least-once, and how to make a handler idempotent given the answer. OpenAPI 3.1 can describe webhook payloads. It cannot describe the delivery contract, which is the part that decides whether someone's handler is correct.
Pagination as a convention. If every list endpoint pages the same way, say so once in a guide rather than making a reader infer it from twelve endpoint pages. If they do not all page the same way, fix that before documenting it.
Idempotency. Whether you support an idempotency key, what it keys on, how long you remember it, and what a replay returns. Without this, every developer writing a payment integration invents their own approach and one of them double-charges somebody.
The test for whether a page should exist
Ask whether the sentence would survive regeneration.
If it comes from the spec, it belongs in the reference and should be generated, because a hand-written copy will drift the first time the spec changes and nobody will notice for months. Field descriptions, types, required flags, status codes: all generated, none hand-maintained.
If it is a decision, a sequence, a caveat or a consequence, it belongs in a guide, because no generator will ever produce it and no regeneration should ever overwrite it.
That line is also the practical reason to keep the two in one system rather than two. Reference pages rebuild from the spec; guides are yours and stay untouched. When they live in separate tools, the guides rot quietly, because updating them is a second job in a second place and nobody remembers on the day the API changed.
Write the errors page first
If you write one guide this quarter, write the one about failure.
Take every non-2xx your API returns and give each an entry: what it means in your domain, whether the client should retry, whether retrying is safe, and what a correct handler does. Not the HTTP definition of 409, which the reader can get from anywhere. Yours.
This page is disproportionately valuable because it is the page people read under pressure, at the point where they are deciding whether your API is reliable or whether they are holding it wrong. A good errors page turns a support ticket into a fix. Its absence turns a transient 429 into a bug report about your uptime.
It is also the page that most directly improves what a generated SDK can do for people, because declared error responses become typed errors rather than one generic failure. If your spec declares no failures, your SDK cannot offer any, and every consumer writes the same catch block from scratch.
Where the spec still does the work
None of this argues for writing your reference by hand. The opposite: the reason to generate the reference ruthlessly is that it frees the only writing time you have for the pages that need a human.
A reference is never finished being wrong when it is hand-maintained. A guide is never written at all when your writing budget is spent retyping schemas.
If you want to know how much of your reference your spec can currently carry, our spec audit scores exactly that: whether operations have prose, whether parameters are described, whether responses declare schemas. The rules it fails are the reference pages you are currently writing by hand without meaning to.
And the guides beside them are the reason API Studio keeps both in one place: the reference rebuilds from the spec, and the words you wrote stay where you put them.
