How to Document an API: Reference, Guides, and OpenAPI in Practice
API documentation is where technical writing meets software engineering most directly, and it's among the highest-value documentation you can produce — because for an API, the docs often are the product. A developer never sees your API's internals; they experience it entirely through the documentation and their own code editor. Excellent API docs drive adoption and cut support costs; poor ones send developers to competitors before they ever make a successful call.
Good API documentation is not one thing but a coordinated set of document types, each serving a different developer need at a different moment. This guide covers the whole picture: the types of docs, how to structure a reference, how OpenAPI transforms the reference workflow, and the guides and samples that turn a reference into an onboarding experience. For measuring whether your docs actually work, pair this with our guide to measuring API documentation with usage data, and for foundations see the beginner's guide to technical writing. The OpenAPI Specification underpins much of what follows.
The Four Types of API Documentation
Complete API documentation comprises four distinct types, and confusing them is a common failure. The reference is the exhaustive, lookup-oriented catalog of every endpoint, parameter, and response — developers don't read it start to finish; they jump to the exact entry they need, so it prioritizes completeness and consistent structure. Getting-started guides (quickstarts) are the opposite: a guided, linear path that takes a brand-new developer from zero to their first successful API call as fast as possible.
The other two are how-to guides and conceptual documentation. How-to guides walk through common real-world tasks that span multiple endpoints — "process a refund," "paginate through results," "handle webhooks" — bridging the gap between individual reference entries and actual goals. Conceptual documentation explains the API's model: its core objects, authentication approach, rate limits, and design principles, giving developers the mental map they need before diving into endpoints. Each type has different rules, and the strongest API docs deliberately provide all four rather than dumping a raw reference and calling it done. This maps directly onto the Diátaxis framework we discuss in our fundamentals guide.
Anatomy of a Reference Entry
Every endpoint in an API reference should follow the same consistent template, because consistency lets developers scan and predict where information lives. A complete reference entry includes: the HTTP method and path (e.g., POST /v1/charges); a one-line description of what the endpoint does; the parameters, split clearly into path, query, header, and request-body parameters, each with its name, type, whether it's required, constraints, and a description; and an example request.
Equally important is the response documentation: the structure of a successful response with every field named, typed, and described, plus a realistic example payload. Document the possible status codes and, critically, the errors this endpoint can return with their meanings — the part most references skimp on and developers need most. Round it out with any authentication or permission requirements and relevant notes on rate limits or idempotency. The discipline is uniformity: when every entry has the same sections in the same order, a developer learns your reference's shape once and navigates the rest effortlessly. Inconsistent entries force them to re-learn the layout on every page.
OpenAPI and Generated Reference Docs
The OpenAPI Specification (formerly Swagger) has transformed how reference documentation is produced. OpenAPI is a standard, machine-readable description of your API — its endpoints, parameters, request and response schemas, and authentication — written in YAML or JSON. From a single OpenAPI file, tools like Swagger UI and Redoc generate a complete, interactive reference site automatically, often including a "try it" console that lets developers make real calls from the docs.
The strategic advantage is a single source of truth. When the OpenAPI description is generated from or validated against the actual API code, the reference can never silently drift out of sync — a change to the API updates the docs, and CI can fail the build if they diverge. This solves the perennial curse of outdated reference docs. The technical writer's role shifts from hand-maintaining every endpoint to curating the descriptions, writing clear summaries and field explanations within the spec, and crafting the conceptual and how-to content that generated references can't produce. Learning to read and edit OpenAPI is now a core API documentation skill, and it connects directly to the automated testing we describe in our data-driven API docs guide.
Writing Getting-Started Guides
The getting-started guide is the most important page in your API documentation, because it determines whether a developer succeeds or abandons in the first ten minutes. Its single goal is time-to-first-successful-call: get the developer from nothing to a working request as quickly as possible. Everything that doesn't serve that goal belongs elsewhere. Start with prerequisites (an account, an API key), then walk through authentication, then a single, complete, copy-pasteable example call, and finally show them the actual response so they can confirm success.
Resist the urge to be comprehensive here — comprehensiveness is the reference's job. The quickstart should cover the single most common, most valuable first task and nothing more, deferring everything else to links. Test it relentlessly against a truly fresh environment and a developer who has never seen your API; every point of friction is a place you lose users. Following the technical writing process of testing docs on real users applies with special force here, because the stakes are highest at the first impression.
Code Samples That Work
Developers learn APIs by copying and adapting code, so your samples are among your most-used content — and broken samples are among the most damaging failures. Every meaningful endpoint and guide should include a working code sample, ideally in the languages your audience actually uses (commonly cURL plus a few popular languages like Python, JavaScript, and Java). cURL is a good baseline because it's language-agnostic and shows the raw HTTP request clearly.
The cardinal rule is that samples must actually run. A copy-pasted example that throws an error destroys trust instantly. The reliable way to guarantee this at scale is to test code samples automatically in CI against a test environment, so a sample that breaks fails the build rather than misleading a reader. Make samples complete enough to run (including imports and setup, not just the one interesting line), use realistic placeholder values, and show the expected output alongside. Where possible, generate samples from the OpenAPI description or maintain them in a tested example repository rather than pasting snippets into prose where they rot unnoticed.
Authentication and Error Documentation
Two areas make or break real integrations and are chronically under-documented: authentication and errors. Authentication is the first wall every developer hits, so document it exhaustively. Explain the scheme (API key, OAuth 2.0, JWT), show exactly how to obtain credentials, show precisely how to include them in a request with a complete example, and document every authentication error and what causes it. A developer stuck on auth never reaches the rest of your API, which is why auth is consistently the highest-drop-off step in analytics.
Error documentation is the mark of a mature API doc set. Document the error format your API returns, list the error codes with their meanings, and — most valuably — tell developers how to resolve each one, not just that it occurred. "401 Unauthorized: your API key is missing or invalid; check the Authorization header" is infinitely more useful than "401: Unauthorized." Comprehensive, actionable error docs are what let developers debug independently instead of filing support tickets. To build all of this into a complete, professional API doc set, Darlo Technical Writing's API Documentation course takes you through documenting a real API end to end with OpenAPI, tested samples, and full error coverage — and a free API reference documentation template is available to structure your next endpoint from the first line.
API Reference Documentation Template
A reusable endpoint template covering method, parameters, request and response schemas, status codes, and error tables — structure any API reference entry consistently from the start.
What are the different types of API documentation?
There are four: the reference (an exhaustive, lookup-oriented catalog of every endpoint), getting-started guides (a linear path to a developer's first successful call), how-to guides (walkthroughs of real tasks spanning multiple endpoints), and conceptual documentation (the API's model, authentication, and design). Strong API docs provide all four, not just a raw reference.
What is OpenAPI and why does it matter for documentation?
OpenAPI is a standard, machine-readable description of an API's endpoints, parameters, and schemas. From one OpenAPI file, tools like Swagger UI and Redoc generate an interactive reference automatically. When the spec is validated against the real API in CI, the reference can't silently drift out of date — solving the perennial problem of outdated reference docs.
How do I stop code samples in my API docs from breaking?
Test them automatically. Execute your documentation's code samples in CI against a test environment so any sample that stops working fails the build instead of misleading readers. Keep samples complete enough to run, use realistic placeholders, show expected output, and where possible generate them from the OpenAPI description or a tested example repository rather than pasting snippets into prose.