Your API Reference Is Not Your API Documentation

2026-05-07 Clinton De Young API Documentation

If you open the docs site of almost any developer tool, you will find a sidebar filled with endpoint names, HTTP verbs, request schemas, and response payloads. Click around long enough, and you will know that POST /v1/charges exists, that it accepts an amount and a currency, and that it returns a Charge object with seventeen fields.

What you still will not know is how to charge a customer.

That gap between knowing what endpoints exist and knowing how to accomplish what you came to accomplish is the gap between an API reference and API documentation. They are not the same thing, and treating them as if they are is one of the most common and most expensive mistakes a developer-facing company can make.

OpenAPI (formerly Swagger) is an excellent reference format. It is machine-readable, version-controllable, and capable of generating SDKs, mock servers, and validation in a dozen languages. Every API team should have one. The mistake is not adopting OpenAPI. The mistake is publishing the rendered OpenAPI spec as “documentation” and assuming the work is done.

Your documentation is not done. Here are five reasons why.

1. A reference answers “what?” but your users want “how?”

OpenAPI’s organizing principle is the endpoint. The sidebar lists resources and operations: Customers, Subscriptions, Invoices, and Webhooks. Each entry describes one operation in isolation.

Your users’ organizing principle is the goal, not the structure. They did not wake up wanting to call POST /v1/subscriptions. They woke up wanting to bill a customer monthly, refund a disputed charge, or send their finance team a CSV of last quarter’s revenue. To get there, they need to know which three endpoints to combine, what order to call them, and which side effects they’ll have to handle along the way.

A reference, by definition, cannot tell them this. A reference is alphabetized; a goal is sequential. A reference is exhaustive; a goal is selective. If you only publish OpenAI specs (the “what?”), your customers have to stumble through the “how?” on their own.

2. You force users to reverse-engineer your conceptual model

Every API encodes a worldview. Stripe’s mental model, which is that a payment is a coordination between a Customer, a PaymentMethod, a PaymentIntent, and a Charge, is not obvious from the endpoint list. Neither is GitHub’s distinction between a repository, a fork, and a workflow run. Neither is the difference, in your API, between an “order” and a “transaction,” or between a “user” and an “account,” or between a “soft delete” and a “hard delete.”

These distinctions are the most important thing your users need to learn, and they are nowhere in your OpenAPI spec. The spec lists the nouns. It does not explain the worldview in which those nouns participate.

Without a conceptual guide, every new developer constructs their own mental model from the schemas. They construct it wrong, build something fragile on top of it, hit production, get paged, and either file a support ticket or quietly migrate to a competitor. Either outcome costs you more than a “Core Concepts” page would have.

3. Auto-generated descriptions are descriptions in name only

Crack open most rendered OpenAPI specs, and you will find descriptions like:

email (string) — The user’s email address.

We know. The field is named email. The type says string. The “description” is a tautology.

The information that would actually help a developer is missing. When is this required versus optional? What format is accepted? What happens if the address bounces? Is it case-sensitive? Is it used for login, for notifications, or for both? Can a user change it, and if so, does the change invalidate active sessions?

The same pattern repeats with code examples. Auto-generated samples are toy curl calls with placeholder values. They demonstrate the syntax of a single request in isolation, not a realistic flow in the language the developer actually uses, with the error handling, idempotency keys, and pagination logic that any production code will need.

You can fix the descriptions and add curated examples, and you should, but doing so well requires writers, not generators. The defaults give you the appearance of documentation without the substance.

4. Cross-cutting concerns have no home

The most important things a developer needs to learn about your API are usually not tied to a single endpoint:

Authentication and key management
Pagination
Idempotency and retries
Rate limits and backoff
Webhooks and event delivery
Errors and status codes
Versioning and deprecation

None of these specifically belongs to POST /v1/charges. They belong to the API. On an OpenAPI-only documentation site, they end up scattered: a sentence in the security scheme, a paragraph in the introduction, and a per-endpoint note repeated 40 times. The reader, hunting for the canonical explanation of how your idempotency keys work, finds three partial explanations and no authoritative one.

These cross-cutting concerns are exactly the areas where a wrong assumption causes the worst bugs, such as duplicate charges, missed webhooks, and runaway retries. They deserve their own first-class guides, organized by concept rather than endpoint. OpenAPI gives them no place to live.

5. There is no path from zero to working code

A reference is a parts catalog. A new user needs an assembly manual.

The first hour a developer spends with your API is the hour that decides whether they keep going. In that hour, they need a guided path:

Install the SDK
Authenticate
Make the first successful call
See a real result

They need to be able to build a small but complete end-to-end flow. They need a “Hello, World” that is actually relevant to your domain, followed by a progression of increasingly realistic recipes.

OpenAPI has nowhere to put any of this. There is no “Getting Started” field in the spec. There is no “Tutorials” section, no “Common Recipes,” no “Troubleshooting.” You can bolt these on as Markdown files served alongside the rendered reference, and many tools let you do so, but doing so does not change the site’s underlying organization. The reference still dominates the navigation, the tutorials sit in a side closet, and the developer’s first impression is a wall of endpoints rather than a friendly path forward.

The teams whose documentation developers actually love (e.g., Stripe, Twilio, Plaid, the Django docs, the Elixir and Phoenix guides) all share a common structure: a conceptual layer that explains the worldview, a task-oriented layer that walks through real goals, a reference layer for lookups, and a troubleshooting layer for when things go wrong. The reference is one of four items. It is necessary. It is not sufficient on its own.

What good documentation actually looks like

The fix is not to abandon OpenAPI. Keep it. Generate your reference from it. A well-maintained OpenAPI spec is a real asset.

However, it is important to recognize that the spec is one input to your documentation, not the whole output. The rest is writing, actual narrative writing, by people who understand both the technical surface of the product and the journey of the developer learning it. That writing belongs in dedicated guides:

A conceptual guide that names the domain model and explains how its parts relate.
Task-oriented tutorials that walk real users through the goals they arrive with, end to end.
Recipes and how-tos for the dozen or so flows that recur across customer integrations.
Cross-cutting guides for auth, pagination, idempotency, webhooks, errors, and versioning.
A troubleshooting section organized by symptom, not by status code.

Your reference catalogs what exists. Your documentation teaches developers how to use it. Both matter. Confusing one for the other is the difference between an API your customers tolerate and one they recommend.