API Documentation
Great API documentation is the difference between a developer integrating in an afternoon and giving up by lunch. It accelerates adoption and slashes support load — every question the docs answer is a ticket you never get.
The most reliable docs are the ones you don't hand-maintain: generate the reference from a machine-readable spec, and the docs stay true to the code by construction.
TL;DR
- Describe the API with an OpenAPI (or GraphQL) spec — machine-readable and the source for tooling.
- Include complete, runnable examples in multiple languages.
- Keep docs in sync with code by generating what you can.
- Offer an interactive "Try It" experience and document errors and auth.
Quick Example
An OpenAPI excerpt — the contract that powers reference docs, the "Try It" UI, and client codegen:
Core Concepts
The four documentation layers
- Reference — every endpoint, parameter, and response (ideally generated).
- Guides — conceptual explanations and tutorials for real tasks.
- Examples — complete, copy-pasteable snippets with error handling.
- Changelog — version history and migration notes.
OpenAPI as the source of truth
OpenAPI (formerly Swagger) is the REST industry standard: a YAML/JSON description of your API that powers interactive docs, client/server codegen, and contract testing. For GraphQL, the schema plays the same role. See REST API Design.
Best Practices
Generate from the spec
Render reference docs from OpenAPI so they can't drift, and add a CI check that fails when the spec is invalid or out of date.
Show complete examples
Cover common use cases in curl, plus a couple of languages (Python, JavaScript). Include authentication and error responses — not just the happy path.
Make it interactive
A "Try It" console (with auth) lets developers call endpoints from the docs and see real responses, which dramatically shortens time-to-first-call.
Document tools
Common Mistakes
Docs that drift from the code
Examples without errors or auth
FAQ
Should I write OpenAPI by hand or generate it?
Either works as long as it's the source of truth. Many teams annotate code to generate the spec; others design the spec first ("spec-first") and generate stubs. Pick one and enforce it in CI so the spec and code never diverge.
How do I keep documentation up to date?
Generate the reference from the spec, version the docs alongside the API, review docs in the same PR as code changes, and fail CI on an invalid or stale spec. The less you maintain by hand, the less drifts.
What makes API docs actually good?
Runnable examples, documented errors and authentication, conceptual guides (not just reference), and an interactive console. Explain the why, not only the how, and call out common pitfalls.
Do GraphQL APIs need separate documentation?
The schema is self-describing and tools like GraphiQL provide interactive exploration, but you still need guides, examples, and auth/error documentation. Self-documenting ≠ fully documented. See GraphQL.
Related Topics
- REST API Design — What you're documenting
- API Versioning — Documenting changes and deprecations
- GraphQL — Schema-driven documentation
- API Design Best Practices — Consistency that's easier to document