Skip to content
DT Nova

API documentation: what good API docs contain, an example structure and the tools

API documentation is what turns an API from something only its builders can use into something another team, a partner or a customer can integrate with on their own. Good API documentation answers every question an integrator has, in the order they have it: what can I do, how do I get access, what do I send, what comes back, what goes wrong and what changes. This guide sets out the parts every set of API docs needs, an example structure, the OpenAPI standard, error formats, versioning and the tools.

New to the topic? Our guide what is an API explains requests, endpoints and keys first.

Standards referred to were read on 12 November 2026: the OpenAPI Specification, the AsyncAPI specification, IETF RFC 9457 on problem details, the OWASP API Security Top 10 2023 and the EU Data Act. This guide is written from the side of the team that builds and documents APIs.

Who reads API documentation

Three readers, with different needs. The evaluator decides whether the API can do the job, and needs an overview, the main use cases and the access model in a few minutes. The integrator builds the connection, and needs a quickstart, authentication, the full reference, examples and errors. The maintainer keeps the integration running for years, and needs the change log, deprecation rules, status page and support route. Documentation that serves only the integrator loses the evaluator on the first page and the maintainer at the first breaking change.

The parts every API documentation needs

PartWhat it answersTypical content
OverviewWhat can this API do, and for whom?Purpose, main resources, use cases, environments (test and production)
QuickstartHow do I make my first successful request?Get credentials, one request, one response, in five minutes
Authentication and authorisationHow do I get access, and to what?OAuth 2.0 flows or API keys, scopes, token lifetimes, how to rotate secrets
ReferenceWhat exactly do I send and get back?Every endpoint or message, parameters, request and response schemas, examples
ErrorsWhat can go wrong and what do I do?Error format, status codes, error types, which errors are worth retrying
Limits and performanceHow hard can I use it?Rate limits, page sizes, payload limits, timeouts
Webhooks and eventsHow am I told when something changes?Event types, payloads, signatures, retries, ordering
GuidesHow do I do a whole task?Step-by-step flows for the main use cases, across several endpoints
Versioning and change logWhat changed and what will break?Version policy, deprecation periods, dated change log
Support and statusWhere do I go when it does not work?Status page, support channel, response times

An example structure for API docs

For a typical business API, such as an order or booking API that partners integrate with, this structure works well:

  1. Introduction: what the API is for, the base URLs for test and production, the data model in one diagram.
  2. Getting started: request credentials, authenticate, list orders, create a test order.
  3. Authentication: the OAuth 2.0 client credentials flow, scopes per resource, token expiry.
  4. Guides: "Create and confirm an order", "Handle a cancellation", "Sync the product catalogue".
  5. Reference: generated from the OpenAPI document, one page per resource, with request and response examples for each operation.
  6. Webhooks: event list, payload examples, signature check, retry schedule.
  7. Errors: the error object, a table of error types with their meaning and the right reaction.
  8. Limits, versioning, change log, support.

Each reference entry should show the method and path, a one-sentence purpose, the parameters with types, which are required and their allowed values, the request body schema with an example, every response status that can occur with an example body, and the scopes required. Examples should use realistic values, not "string" and "123".

OpenAPI: the standard description for HTTP APIs

The OpenAPI Specification defines, in its own words, a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without access to source code or additional documentation. The latest published version, read on 12 November 2026, is 3.2.1, dated 10 September 2026. In this version, schema objects follow JSON Schema draft 2020-12, which means the same schema can validate data in code and describe it in the documentation.

A single OpenAPI document can feed the reference pages, a mock server for early integration, client libraries, contract tests in the build pipeline and API gateway configuration. Treat it as code: keep it in the repository, review changes to it, and fail the build when the implementation and the description disagree. For message-based APIs, the AsyncAPI specification plays the same role; its current version on asyncapi.com is 3.1.0.

Document errors in a standard format

Error handling is where most integrations spend their time, and where most API documentation is thinnest. IETF RFC 9457, Problem Details for HTTP APIs (July 2023, Standards Track, replacing RFC 7807), defines a machine-readable format for error details in HTTP responses, so APIs do not each invent their own. Whatever format you use, document for each error type what it means, whether retrying makes sense, and what the integrator should show their user. A table of ten well-explained errors saves more support time than any other page.

Versioning and deprecation

  • State what counts as a breaking change: removing a field, changing a type, making an optional field required, changing the meaning of a value.
  • Say how versions are expressed: in the path, a header or a date-based version.
  • Publish a deprecation period and keep to it. Announce removals with a date, in the change log and by email to registered integrators.
  • Keep a dated change log, newest first, with a link to each affected reference entry.

Security and the documentation inventory

The OWASP API Security Top 10 2023 lists "API9:2023 Improper Inventory Management" among the main API risks: old, undocumented or forgotten API versions and endpoints that stay reachable. Complete documentation is part of the defence: every endpoint that exists is documented, and every documented endpoint has an owner. Never put real credentials, personal data or internal hostnames in examples, and describe the authorisation rules per endpoint, since broken object level authorisation is first on the same list.

APIs, documentation and the EU Data Act

The EU Data Act makes documentation a legal topic for some APIs. Article 33(1)(c) requires participants in data spaces that offer data or data services to describe the technical means to access the data, such as application programming interfaces, and their terms of use and quality of service, sufficiently to enable automatic access and transmission. For connected products, data access for users is required by design from 12 September 2026. Our EU Data Act guide explains the rules.

Tools for API documentation

Tools fall into three groups. Description editors and linters check the OpenAPI document against style rules, such as Spectral or Redocly CLI. Renderers turn the description into reference pages, such as Swagger UI, Redoc, Scalar or Stoplight Elements. API portals combine guides, reference, keys and analytics, either as a hosted product or as part of an API gateway. For most companies, a static documentation site built from the repository, with the guides in Markdown and the reference generated from OpenAPI, is easy to keep current and costs little to run.

A checklist before you publish

  • A newcomer can make a first successful request in under 15 minutes.
  • Every endpoint, parameter and field is in the reference, with types and examples.
  • Every error type has a meaning and a recommended reaction.
  • Authentication, scopes and limits are explained with examples.
  • The OpenAPI document is tested against the implementation in the build.
  • The change log and deprecation policy are published.
  • No secrets or personal data in examples.

How we help

We design APIs description-first: the OpenAPI document is written and reviewed with your integrators before the code, then tested in every build. Every API integration and backend we build comes with the reference, the guides and the change log in the same repository, which is in your company's account. You own the code and the documentation.

Questions people ask

What is API documentation?

API documentation is the reference and the guidance that tell another team or system how to use an API: which endpoints or messages exist, how to authenticate, what each request and response looks like, which errors can happen, and the rules on limits and versions. Good documentation lets an integration be built without meetings or access to the source code.

What is the difference between OpenAPI and Swagger?

OpenAPI is the specification, a standard format for describing HTTP APIs, maintained by the OpenAPI Initiative under the Linux Foundation. Swagger is the older name of the specification up to version 2.0 and today the name of a family of tools that read and display OpenAPI descriptions. You write an OpenAPI document; you can display it with Swagger UI or many other tools.

Should API documentation be generated from code?

The reference part can and usually should be generated, or the code generated from the description, so the two cannot drift apart. The guides, examples and explanations of business rules have to be written by people. The best results come from treating the OpenAPI document as part of the code, reviewed and tested in every change.

How do you document an event-driven API?

Event-driven and message-based APIs, such as those using MQTT, Kafka or WebSockets, are commonly described with the AsyncAPI specification, which plays the same role for messages as OpenAPI does for HTTP requests. The current version on asyncapi.com was 3.1.0 when we checked on 12 November 2026.

Who should write API documentation?

The team that builds the API owns the reference and keeps it correct. A technical writer or a product person improves the guides and examples. The final test is someone outside the team building a small integration from the documentation alone and noting where they got stuck.

Sources