API documentation: OpenAPI, examples and keeping it up to date

API documentation is needed by everyone who works with the API: the frontend, the mobile app, partners and new developers. The de facto standard is the OpenAPI specification, from which interactive docs, clients and tests are generated automatically. To keep documentation from going stale, generate it from code or check it against the code in CI on every change.

Here is what OpenAPI is, which approach to choose, what good documentation contains and how to keep it current.

What is OpenAPI?

OpenAPI is a format for describing HTTP APIs in YAML or JSON: which endpoints exist, which parameters they take, what they return, which errors can occur and how authentication works. It is a machine-readable contract from which tools build documentation, client libraries, mocks and checks.

paths:
  /orders/{id}:
    get:
      summary: Get an order
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Order found
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '404':
          description: Order not found

What a specification gives you:

• interactive documentation — send a request straight from the page;
• client generation — typed code for the frontend and mobile apps;
• mocks — the frontend works against a fake API while the backend is being built;
• checks — tests compare real responses against the specification.

Contract first or code first?

There are two approaches: write the specification first, discuss and approve it, then implement (contract-first), or write the code and generate the specification from it (code-first). The first is better for public APIs and teams working in parallel; the second for internal APIs of small teams.

Criterion	Contract-first	Code-first
Starting point	The specification file	Endpoint code
Parallel work	The frontend starts at once on mocks	Waits for implementation
Risk of drift	Code must be checked against the spec	Low, the spec comes from code
Suits	Public and partner APIs	Internal APIs, fast changes

On designing endpoints, see how to design a REST API and REST vs GraphQL vs gRPC.

Photo: Unsplash

What should good documentation contain?

Good documentation answers a developer's questions without emailing the author: how to get access, how to make the first request, what each error means and what changed in the latest version. An auto-generated spec alone is not enough — explanations and examples are needed.

1. Quick start. How to get a key and make a first successful request in five minutes.
2. Authentication. The method, token lifetime and refresh — see sessions vs JWT vs OAuth.
3. Examples. Real requests and responses for every endpoint, not just schemas.
4. Errors. A consistent error format, a list of codes and what to do about each.
5. Limits. Request rate and payload limits — see rate limiting.
6. Webhooks. Which events arrive, how to verify signatures and how to handle retries.
7. Changelog. What changed, when and whether there are breaking changes.

How do you keep documentation from going stale?

Documentation goes stale when it is updated by hand separately from the code. The fix is to make it part of the development process: the spec lives in the repository, changes in the same pull request as the code, and CI checks they match.

• the specification is stored in the repository next to the code;
• API changes without spec changes do not pass review — see code review best practices;
• contract tests check that responses match the schema;
• a spec linter catches breaking changes;
• documentation is published automatically on every release.

How does documentation help the business?

Documentation saves the team's and partners' time: integrations connect faster, support gets fewer questions and handing the project to another team is easier. For products where the API is part of the customer offering, documentation quality directly affects sales.

• new developers become productive in days rather than weeks — see developer onboarding;
• partners integrate without calls with your engineers;
• API knowledge is not lost when you change vendors;
• technical audits go faster and cost less.

In short

• OpenAPI is the standard machine-readable API contract.
• Docs, clients, mocks and checks are generated from the specification.
• Contract-first suits public APIs and parallel work; code-first suits internal ones.
• Good docs include a quick start, examples, errors, limits and a changelog.
• The spec lives in the repository and is checked in CI, or it will go stale.