Api reference docs

API reference docs

Reference docs answer "how do I call this exactly": every endpoint, parameter, response, and error. The winning approach blends generation (complete, never drifts) with curation (examples and guidance a generator cannot produce), because pure generation is complete but useless and pure hand-writing is helpful but stale.

Method

1. Generate the skeleton from the source of truth. From the OpenAPI/GraphQL schema, proto, or code annotations (see openapi-contracts, graphql-schema-design): endpoints, parameters, types, and required/optional status stay complete and in sync with the actual API because they come from it. Hand-maintained parameter lists drift the first time someone adds a field.
2. Curate what generation cannot express. Every endpoint needs a realistic example (request and response, with real-looking values), a one-line "when to use this", and the non-obvious behavior (side effects, rate limits, pagination: see api-pagination-design, rate-limiting). The generated schema says a field is a string; the curated note says what string and why.
3. Document every error, not just the happy path. What errors each endpoint returns, what causes them, and how to fix them (see api-error-responses): error docs are what turn a support ticket into a self-service fix. Reference docs that only describe success leave the consumer stranded exactly when they need help.
4. Show authentication and the first real call. How to authenticate (see authn-design, oauth-flows), then a complete working example from zero to a successful response: the reference doubles as the quickstart's detailed backing (see readme-writing's quickstart, which links here). A reference nobody can make their first call from has failed at its one job.
5. Keep examples tested and current. Runnable, verified examples (docs-as-code: run them in CI so a breaking change fails the docs build too: see docs-as-code): a copy-pasted example that errors is worse than none, because it destroys trust in the whole reference. This is the discipline that keeps generated-plus-curated honest.
6. Version the reference with the API. Consumers on different versions need the docs for their version (see api-versioning); a single reference that silently describes the latest version misleads everyone not on it. Deprecations marked clearly with migration paths (see api-deprecation).

Boundaries

• Reference docs answer "how", not "why" or "what should I build": conceptual guides and tutorials (see tutorial-writing) serve those, and a reference alone leaves beginners lost (see docs-information-architecture's four-quadrant split).
• Generation quality depends on source annotation quality; garbage descriptions in the schema produce garbage docs (see structured-output's field-description rule, applied to your own API).
• Interactive reference (try-it consoles, request builders) raises the value but adds infrastructure; worthwhile for public APIs, over-investment for a small internal one.