How to Write Good API Documentation

Good API documentation is the difference between a developer integrating in an afternoon and abandoning your product before dinner. It should answer three questions fast: what does this API do, how do I make my first call, and what happens when things go wrong. This guide walks through what to document, how to structure it, which tools to use, and the mistakes that quietly ruin otherwise decent references.

Step 1: Cover the non-negotiables

Every API reference, regardless of size or stack, needs the same core sections. Miss one and developers will file a support ticket or leave.

• Authentication - Explain the scheme (API key, OAuth 2.0, JWT), where the credential goes (header, query, body), how to obtain and rotate it, and what scopes exist.
• Base URL and environments - Production, sandbox, and regional hosts, with a note about which one to use when.
• Endpoints - HTTP method, path, purpose, and a one-line summary in the sidebar.
• Request and response schemas - Every field, its type, whether it is required, allowed values, and defaults.
• Error codes - HTTP status, error code string, human message, and how to recover.
• Rate limits - Requests per minute, burst rules, the headers that surface remaining quota, and the status returned when exceeded.
• Pagination - Cursor or offset, page size limits, and what the next-page token looks like.
• Versioning - How versions are declared (URL, header, or accept-type), the deprecation policy, and the sunset window.
• Changelog - Dated, human-readable entries so integrators know what changed between releases.

Step 2: Write an OpenAPI spec as the source of truth

Handwritten Markdown drifts from reality within weeks. Describe your API in OpenAPI (formerly Swagger) instead. A single YAML or JSON file becomes the source of truth that generates documentation sites, SDKs, mock servers, contract tests, and Postman collections.

Store the spec in the same repository as the code, wire it into CI so a schema change fails the build if docs are not updated, and generate client libraries from it rather than typing them by hand. The spec also lets you validate real traffic against the contract, which catches undocumented fields before customers do.

Step 3: Pick a renderer and a docs platform

You do not need to build a docs site from scratch. Popular options include:

• Swagger UI - Free, interactive, ships with a try-it-out console. Great for internal or small public APIs.
• Redoc - Clean three-column layout that scales to large specs; open source and easy to host.
• Mintlify - Modern hosted docs platform with search, versioning, and code samples generated from OpenAPI.
• Stoplight - Visual OpenAPI editor plus a docs portal; good if non-engineers help maintain the spec.
• Bump.sh - Diff-driven docs that highlight breaking changes on every commit.

Whatever you pick, host docs on your own domain, keep the URL structure stable, and make search actually work.

Step 4: Add a quick-start that copies and runs

The first page a developer sees should get them to a successful call in under five minutes. Provide a snippet in at least three languages - typically curl, JavaScript, and Python - using realistic values.

curl https://api.example.com/v1/invoices \
  -H "Authorization: Bearer sk_live_9c7..." \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cus_8HgQ2", "amount_cents": 4900, "currency": "usd" }'

Then show the exact response body they should expect, including headers that carry rate-limit info or request IDs.

Step 5: Document every error, not just the happy path

For each endpoint, list the errors it can return. A vague "400 Bad Request" is useless; developers need the specific error.code, the trigger, and the fix.

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "code": "invalid_currency",
    "message": "Currency 'xyz' is not supported. Use an ISO 4217 code.",
    "param": "currency",
    "request_id": "req_01HRTX7..."
  }
}

Include the request ID field explicitly - it is what your support team will ask for first.

Step 6: Use realistic examples and keep them fresh

Replace foo, bar, and string with values that match your actual domain: an invoice ID that looks like your invoice IDs, an amount in the right currency, a timestamp in the format you really return. Generate examples from the OpenAPI spec so they cannot drift, and run them as part of your test suite.

Common mistakes to avoid

• Out-of-date examples - Code samples that no longer compile because a field was renamed six months ago.
• Missing error documentation - Only the 200 response is shown; developers guess the rest.
• No auth walkthrough - The docs mention "use your API key" without saying where to get one or which header to put it in.
• Undocumented rate limits - Developers discover the limits only after production traffic gets throttled.
• No changelog - Breaking changes ship silently, and integrators find out from bug reports.
• Wall-of-text reference - No search, no sidebar, no anchor links; finding an endpoint requires Ctrl+F.
• Marketing copy in the reference - Save the pitch for the landing page; the reference should be scannable and dense.

Ship it like a product

Treat documentation as a product surface, not an afterthought. Version it alongside code, review it in pull requests, measure which pages developers land on and bounce from, and read the support tickets - every repeat question is a docs bug. Do these things and your API stops being a black box and starts being something developers actually enjoy using.