OpenAPI-Generated vs Hand-Written API Docs: Choosing the Right Approach
Ask two experienced technical writers how to document an API and you may get two opposite answers. One will say generate everything from an OpenAPI specification so the docs never drift from the code; the other will say generated reference is cold and useless without hand-written guides that teach a developer how to actually accomplish something. Both are right, because they are describing different layers of the same deliverable.
This guide compares the main approaches to API documentation — generated reference, hand-written narrative, reference-first versus tutorial-first structure — and shows why the best docs combine them deliberately rather than choosing one. If you are newer to the discipline, our beginner's guide to technical writing covers foundations, and our guide to writing great API reference goes deep on the reference layer. For the specification standard itself, the OpenAPI Specification is the reference point this article assumes.
The two jobs API docs must do
Before comparing approaches, be clear on what API documentation is for, because the right approach depends entirely on which job you are optimizing. API docs serve two fundamentally different needs. The first is lookup: an experienced developer who knows roughly what they want and needs the exact endpoint, parameter, type, or error code. This reader wants a dense, complete, accurate reference and will be annoyed by prose. The second is learning: a developer new to your API who needs to understand the mental model, make their first successful call, and see a realistic end-to-end flow. This reader wants narrative, context, and a working example. A single format cannot serve both well, which is why the generated-versus-hand-written debate is a false choice — you almost always need both, aimed at different moments in the developer's journey.
Generated reference from OpenAPI
The strongest argument for generating reference documentation from an OpenAPI (formerly Swagger) specification is that the docs stay synchronized with the code. Every endpoint, parameter, request schema, response shape, and error code is defined once in the spec and rendered automatically by tools like Swagger UI, Redoc, or Stoplight. When the API changes, the docs change, eliminating the single most common failure of API docs: reference that lies. Generation also gives you an interactive 'try it' console, machine-readable schemas that power client-SDK generation, and consistency across every endpoint for free. The limitation is that generated reference is only as good as the spec behind it: bare specs produce bare docs. Rich descriptions, meaningful examples, and prose on each field must still be authored — in the spec's description fields — by a writer who cares. Generated does not mean unauthored; it means the writing lives in the spec instead of in separate pages. Teams that treat the OpenAPI file as a writing surface, not just a machine contract, get reference docs that are both accurate and genuinely readable.
Hand-written guides and tutorials
Generated reference cannot teach. It can tell a developer that an endpoint exists and what parameters it takes, but not why they would use it, how it fits with other endpoints, or what a complete authentication-to-result flow looks like. That is the job of hand-written content: a getting-started guide that gets a developer to their first successful call in minutes, conceptual pages explaining the API's mental model and object relationships, task-based how-to guides for common goals, and tutorials that walk an end-to-end scenario. This content is expensive because it must be written and maintained by hand, and it does drift from the code if neglected — but it is what turns a developer from confused to productive. The best-known API docs in the industry, such as Stripe's, win precisely because of this hand-written layer, not the reference. Our guide to task-based documentation covers how to structure these how-to pages.
Reference-first vs tutorial-first
A second axis of comparison is what a developer hits first. Reference-first sites lead with the endpoint catalog; tutorial-first sites lead with a guided onboarding path. Reference-first suits APIs whose audience is already expert and knows what they want — internal APIs, or additions to a platform developers already use. Tutorial-first suits APIs competing for adoption, where the first ten minutes decide whether a developer stays. The Diátaxis framework, widely adopted in the documentation community, formalizes this by separating tutorials, how-to guides, reference, and explanation into four distinct modes with different goals — a useful lens for deciding what each page should be and refusing to let a tutorial rot into a reference dump. Most successful developer platforms are tutorial-first on the surface with deep reference one click away.
The hybrid approach most teams need
The practical answer for nearly every team is a layered hybrid: generate the reference from OpenAPI so it stays accurate, hand-write the getting-started, conceptual, and tutorial content so developers can learn, and link the two densely so a reader can move from a tutorial into the exact reference entry and back. Keep both under the same information architecture and search. This gives you accuracy where accuracy matters most (reference) and pedagogy where learning matters most (guides), while avoiding the two classic failure modes — reference that lies and guides that overwhelm. Treat the OpenAPI spec and the narrative docs as one product with two production pipelines, not two competing camps.
Choosing tooling for each layer
For the generated reference layer, Swagger UI, Redoc, and Stoplight render OpenAPI specs, while Postman collections give developers a runnable sandbox and can double as living examples. For the hand-written layer, a docs-as-code static site (Docusaurus, MkDocs, or a purpose-built developer-docs platform) keeps narrative content in version control alongside the spec. The goal is a single published site where generated and authored content sit side by side seamlessly. If you want a proven starting structure, our downloadable API documentation template lays out the full information architecture — getting started, authentication, core concepts, how-to guides, and reference — and the API-documentation track in our technical writing courses teaches how to author each layer, including how to write rich OpenAPI description fields. For the specification itself, keep the OpenAPI Specification open as your reference while you author.
The Complete API Documentation Template
A full information-architecture template for developer docs — getting started, authentication, core concepts, how-to guides, and reference — ready to fill in.
Should I generate API docs from OpenAPI or write them by hand?
Both. Generate the reference from your OpenAPI spec so it stays synchronized with the code, and hand-write the getting-started guides, concepts, and tutorials that teach developers how to use the API. They serve different readers and different moments, so it is not an either-or choice.
Do generated reference docs still need a writer?
Yes. Generation only renders what is in the spec, so the descriptions, examples, and per-field prose must still be authored — inside the spec's description fields. Treat the OpenAPI file as a writing surface, not just a machine contract, or you get bare, unhelpful reference.
What tools produce good API documentation?
For generated reference, Swagger UI, Redoc, and Stoplight render OpenAPI specs, and Postman provides a runnable sandbox. For hand-written guides, a docs-as-code static site such as Docusaurus or MkDocs keeps narrative content in version control alongside the spec.