Describe your API in a machine-readable file, then generate a reference from it and add guides that show the first working request. Document authentication, errors and limits, include copyable examples, and publish the docs from the same repository as your code so every release updates them together.
Good API docs aren't one document. They're a stack of layers, each answering a different question a developer has at a different moment: what can this do, how do I make my first call, and why did it just break. Get the layers right and the writing gets much easier.
The four layers every API doc set needs
Layer one: the description file underneath everything
A machine-readable description of your API, usually an OpenAPI file, sits at the bottom. Every docs tool builds on it, so errors here spread everywhere. Lint it before anything else. Redocly offers a CLI to lint, bundle and ship API descriptions, which catches mistakes before they reach a published page.
Layer two: the reference, generated, not hand-typed
Generate an interactive reference from that file so each endpoint lists its parameters and responses. A reference built from the source file stays accurate, because when the file changes, the reference follows. Hand-written references drift within weeks.
Layer three: the quickstart
A quickstart gets a new developer from sign-up to a first successful request, with an example they can copy. The first request is where most developers decide if your docs are worth the time, so this page deserves more care than any other.
Layer four: the pages people search when something breaks
Authentication, error responses, rate limits and a changelog, all in plain language. Nobody reads these for pleasure. They arrive from a search box with an error message in hand, so make each page answer one problem fast.
Your build order in five steps
- Write or generate the description file and lint it. Fix every warning before you publish anything. A linter in your release process stops broken descriptions reaching developers.
- Generate the reference from that file. ReadMe, Mintlify and Redocly all produce an API reference, and a try-it panel lets developers send a test call from the page.
- Write the quickstart with a copyable first request. Any of the docs platforms below can host it, including a static site built with Docusaurus.
- Cover authentication, errors, limits and changes. Give each its own page, and keep a changelog developers can scan, with the newest change at the top.
- Keep the docs in version control and ship them with the code. Publish them with the same process as your code releases. Docs that ship with the code are less likely to go stale.
Retiring an endpoint: tell the response, not only the docs
Documenting an endpoint isn't the end of the job, because endpoints get retired. Most teams handle that with a line in the changelog and an email, and then wonder why integrations break on the day. Plenty of developers never reread your docs once their code works.
There's a standard for this. RFC 8594, The Sunset HTTP Header Field, published by the IETF, defines a Sunset response header that indicates a URI is likely to become unresponsive at a specified point in the future. It also defines a sunset link relation that points to information about the change, such as your migration guide.
The value is that the warning travels with every response. A developer's monitoring can pick up the header and flag the retirement long before anything fails, whether or not anyone on their team reads your changelog. So when you deprecate an endpoint, send the header, link it to the notes, and mention the header in your changelog and deprecation pages. Developers can then detect a retirement from the response itself, not only from reading your docs.
If your API sits behind a gateway, that's often the easiest place to add response headers consistently; my guide to API gateways for growing teams covers the options.
Picking a docs platform that fits your stack
Mintlify
Its page says docs stay in Git as Markdown or MDX, covering API references, guides and help centres, without requiring an OpenAPI specification. Because the files live in Git, you can move them to another platform.
ReadMe
An API documentation platform with guides, recipes, an API reference, a changelog, OpenAPI support, version control and sync with GitHub.
Redocly
API documentation and tooling: a CLI to lint, bundle and ship descriptions, a reference with try-it, and a mock server. Its standout is linting before you publish.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
GitBook
A docs platform with an API section and GitHub sign-in. Its standout is flagging outdated content, which helps with the slow drift every doc set suffers.
Docusaurus
An open source documentation framework. You write docs and blog posts in MDX, it builds static HTML files you can serve, and because it's React-based you can customise everything.
For a fuller comparison, including tools not listed here, my roundup of API documentation tools goes wider.
The advice I'd give a team starting from scratch
Put the description file under version control and lint it on every release, because everything else is built on it. Generate the reference, never type it. Spend your writing time on the quickstart and the error pages, since that's where developers either succeed or leave. And when an endpoint's days are numbered, say so in the response with a Sunset header as well as in the docs. Docs tell people who look; headers tell people who don't.
Want your tool on this list? Featured spots and reviews here are paid partnerships. Here's how to partner with me.
Frequently asked questions
Do I need an OpenAPI file to document an API?
Not always. Mintlify's page says you don't need an OpenAPI specification, though other tools list OpenAPI support for generating references.
What should API documentation include?
A quickstart, a reference for every endpoint, authentication, error responses, rate limits, examples and a changelog.
How do I stop docs going out of date?
Keep them in version control with the code, and use a platform that flags outdated content, as GitBook's page describes.
Should docs live in the same repository as the code?
It helps. Keeping docs in Git as Markdown or MDX, with sync to GitHub, lets teams review docs changes alongside the code they describe.
How do I warn developers that an endpoint is being retired?
Note it in your changelog and deprecation pages, and send the Sunset response header defined in RFC 8594, with a sunset link pointing to details of the change.
