# API Documentation: A Complete Guide — Routebase > What API documentation is made of, why it drifts away from the API it describes, what separates documentation people use from documentation they abandon, and how to publish it. Canonical page: https://routebase.dev/guides/api-documentation/ Guide overview · 10 chapters · Last reviewed 2026-09-13 · The Routebase Team Your API documentation is the only part of your API that most people meet before they decide whether to use it. That makes it a product surface, and it is usually maintained like an afterthought. This guide covers what belongs in API documentation, how to write the parts that a generator cannot write for you, how to keep it true while the API keeps moving, and how to publish it. Every chapter stands on its own, so you can start with the one that matches your situation. ## Three layers that do different jobs Almost every complaint about API documentation comes from one layer being asked to do another layer's work. The **reference** is the complete, mechanical description of the surface, meaning every endpoint, every parameter, every response and every error. It is looked at rather than read, it has to be exhaustive, and it is the layer a machine can generate from your contract. The **guides** walk one reader through one task, from an empty editor to a working call. They are read once, they are allowed to be opinionated, and they are the layer that decides whether somebody gets to their first success today or next week. The **concepts** explain the model behind the API. A reader who does not know what your API means by an order, an idempotency key or a webhook delivery attempt will misuse endpoints that are documented perfectly. _Figure: The reference is generated from the contract and is complete by construction. The guides and the concept pages are written once and then maintained deliberately, which is why the three layers age at very different speeds._ ## Why documentation drifts In most setups the documentation is a copy. The API is defined in one place, usually in code or in an OpenAPI document, and it is described somewhere else in prose that a person typed. Two copies of the same fact only stay equal while somebody keeps making every change twice. That person is busy during exactly the releases where the change matters most, so the gap opens quietly and nobody finds out until a consumer builds against a field that no longer exists. The fix is not more discipline. The fix is removing the second edit wherever the fact is mechanical, which is what [generated reference documentation](/guides/api-documentation/keeping-api-documentation-up-to-date/) does, and then spending the recovered attention on the writing that no generator can produce. ## What separates documentation people use Four properties show up in every set of docs that developers actually like, and none of them is about visual design. The first call works. A reader who can paste one request and get a real response inside five minutes will forgive a lot afterwards. A reader who is still hunting for a base URL after twenty minutes is already evaluating somebody else. Every error has a way out. An error table that lists status codes without saying what caused each one and what to do next is a list of bad news. Examples are real. A response example that was written by hand two releases ago is worse than no example, because a reader trusts it and builds against it. The answer is where the question is. Auth belongs on the endpoint that needs it, the retry rule belongs next to the rate limit header, and the migration note belongs on the deprecated field. ## Documentation, developer portal, API reference The three terms get used interchangeably, and the distinction that matters is small. **Documentation** is the content. An **API reference** is the generated layer of it. A **developer portal** is the site that carries the content for external readers, usually with search, a version switcher, code samples, a playground and your own branding. Teams with a public API tend to say developer portal, while teams with an internal API tend to say docs, and both mean the same body of work. The real decision behind the word is not which one you build. It is who hosts the result, which [publishing and hosting](/guides/api-documentation/publishing-and-hosting-api-documentation/) covers. ## The short answer If you take one rule away, take this one. Generate everything that can be derived from your contract, write the part that cannot, and publish both from one place so there is never a second copy to forget. The rest of the guide is that rule taken apart. | Chapter | Answers | |---|---| | [What belongs in API documentation](/guides/api-documentation/what-belongs-in-api-documentation/) | The pages nearly every API needs, and what each one has to deliver | | [How to write it](/guides/api-documentation/how-to-write-api-documentation/) | Summaries, descriptions, examples, enums and errors that answer the real question | | [Keeping it up to date](/guides/api-documentation/keeping-api-documentation-up-to-date/) | Generated reference, pinned snapshots, doc versions and changelogs | | [Interactive documentation](/guides/api-documentation/interactive-api-documentation/) | What a playground must do, which servers it may show, and what never belongs in docs | | [Documentation for agents](/guides/api-documentation/api-documentation-for-ai-agents/) | The `llms.txt` convention, Markdown twins and what an agent can do with them | | [Publishing and hosting](/guides/api-documentation/publishing-and-hosting-api-documentation/) | Subdomains, your own domain, internal against public, and taking a version back | | [Docs as code](/guides/api-documentation/api-docs-as-code/) | Markdown in the repository against an editor in the portal, and what syncing costs | | [Measuring documentation](/guides/api-documentation/measuring-api-documentation/) | Failed searches, reader feedback and the numbers worth acting on | | [Structure and navigation](/guides/api-documentation/api-documentation-structure-and-navigation/) | Trees against flat lists, search, versions and branding that stays out of the way | | [Choosing a tool](/guides/api-documentation/api-documentation-tools/) | The criteria that decide this, without a vendor list | ## In Routebase Routebase builds the documentation portal out of the same workspace the API lives in. Written pages and generated API references sit in one content tree, so a guide about pagination and the endpoint it describes are two nodes of the same version rather than two systems. _Screenshot: Written pages, folders and the generated API reference live in one tree per documentation version, and the page on the right is edited in the same place it is published from._ The reference comes from a published specification version rather than from prose, the portal carries your branding on your own domain, and every build also emits the machine-readable files an agent can read. Start with the [Documentation Overview](https://docs.routebase.dev/doc-overview/) in the product documentation, or read on. The [API documentation feature page](/api-documentation/) has the short version of how the portal fits into the rest of the lifecycle. ## Frequently asked questions ### What is API documentation? API documentation is everything a developer needs to call your API successfully without asking you. It has three layers that do different jobs. The reference lists every endpoint, parameter, response and error. The guides walk somebody through a task from start to finish. The concept pages explain the model behind the API, meaning what an order is, what a webhook delivery is and what happens when one fails. ### What should API documentation include? Beyond the endpoint reference, most APIs need a Getting Started page that ends in a working first call, an Authentication page, and a page listing the environments and base URLs. After that come an error reference with a way out of every error, rate limits with a retry strategy, webhooks with signature verification, client libraries where they exist, and a changelog. Each of those answers a question that otherwise reaches your support inbox. ### Why does API documentation get out of date? Because in most setups the documentation is a copy. The API is defined in one place and described in another, so every change has to be made twice by somebody who remembers to do it. Generating the reference from the contract removes the second edit, and what remains is the writing that no generator can do for you. ### What is the difference between API documentation and a developer portal? The words are used for the same thing in most conversations. Documentation is the content, while a developer portal is the site that carries it, usually with search, a version switcher, a playground and your branding on top. If your API has external consumers you end up needing both, and the decision is not which one to build but who hosts the result. ## Chapters in this guide 1. [What Belongs in API Documentation](https://routebase.dev/guides/api-documentation/what-belongs-in-api-documentation/): The pages nearly every API needs beyond the endpoint reference, what each one has to deliver, and how to tell a page that is doing its job from one that only looks complete. 2. [How to Write API Reference Documentation](https://routebase.dev/guides/api-documentation/how-to-write-api-documentation/): Summaries against descriptions, the questions a description has to answer, examples per response, enum values with meaning, and errors a reader can act on. 3. [Keeping API Documentation Up to Date](https://routebase.dev/guides/api-documentation/keeping-api-documentation-up-to-date/): Why documentation drifts away from the API, what to generate and what to write, how pinned snapshots and documentation versions work, and where a changelog comes from. 4. [Interactive API Documentation](https://routebase.dev/guides/api-documentation/interactive-api-documentation/): What a try-it playground has to do to be useful, which servers and credentials it may carry, how code samples earn their place, and what must never reach a documentation page. 5. [API Documentation for AI Agents](https://routebase.dev/guides/api-documentation/api-documentation-for-ai-agents/): What an agent can actually read from a documentation site, the llms.txt proposal, Markdown versions of pages, and why a generated endpoint page has to be readable as text. 6. [Publishing and Hosting API Documentation](https://routebase.dev/guides/api-documentation/publishing-and-hosting-api-documentation/): Where documentation lives, subdomain against your own domain, who is allowed to read it, how to take a version back, and the settings that decide how the site is found. 7. [API Docs as Code](https://routebase.dev/guides/api-documentation/api-docs-as-code/): Markdown in the repository against an editor in the portal, what each arrangement buys, what keeping both in step actually costs, and where the contract itself should live. 8. [Measuring API Documentation](https://routebase.dev/guides/api-documentation/measuring-api-documentation/): The signals that tell you whether documentation is working, why failed searches are the best backlog you have, how to read reader feedback, and which numbers to ignore. 9. [API Documentation Structure and Navigation](https://routebase.dev/guides/api-documentation/api-documentation-structure-and-navigation/): Trees against flat lists, how readers actually find a page, what a version switcher has to do, and branding that supports the content instead of competing with it. 10. [What to Look For in API Documentation Tools](https://routebase.dev/guides/api-documentation/api-documentation-tools/): Nine criteria that decide whether a documentation tool still fits in two years, written as questions to ask rather than as a list of vendors. --- [Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.