API Documentation

1Why Documentation Is Part of the API, Not an Afterthought

An API's real interface is not the code — it's what a consumer who has never seen your source can learn from the docs alone. Two APIs with identical implementations but different documentation are, from a client's perspective, different products: one is usable, the other requires reverse-engineering by trial and error. Documentation is the contract a client programs against, which is why it needs the same rigor as the code enforcing that contract.

2OpenAPI: a Machine-Readable Contract, Not Just Prose

The dominant standard for REST API documentation is OpenAPI (formerly Swagger) — a JSON/YAML document describing every endpoint, its parameters, request/response shapes, and status codes, in a format tools can parse:

openapi: 3.0.3
info:
  title: Orders API
  version: 1.2.0
paths:
  /orders/{id}:
    get:
      summary: Retrieve a single 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: No order with this id
components:
  schemas:
    Order:
      type: object
      required: [id, status, total_cents]
      properties:
        id: { type: integer }
        status: { type: string, enum: [pending, confirmed, shipped, cancelled] }
        total_cents: { type: integer }

Because this is structured data, not free-form prose, tooling can generate an interactive explorer (Swagger UI, Redoc), typed client SDKs, and — critically — validate real requests/responses against the schema in tests (see section 5).

3Schema-First vs. Code-First Generation

Two opposing workflows produce the same OpenAPI document, with different failure modes:

Neither approach is safe by construction — both need an explicit verification step (section 5) or they degrade into documentation nobody trusts, which is worse than no documentation at all because it actively misleads.

4What Every Endpoint's Documentation Must Cover

A documented endpoint that omits any of the following forces the consumer back into reading source code or guessing:

• Every parameter — path, query, header, and body — with type, whether it's required, and any constraints (min/max, enum, format)
• Every realistic response status code, not just the happy path — 200 and 400, 401, 404, 409, 422, 429 as applicable, each with its response shape
• Authentication requirements — which scheme (API key, Bearer token, OAuth2 scope), and which scopes/permissions this specific endpoint needs (see backend/api-design/10-api_security for the auth mechanisms themselves)
• Example request and response bodies — a schema alone rarely conveys shape as clearly as one concrete, realistic JSON example
• Rate limit behavior, if the endpoint is limited (see backend/api-design/07-rate_limiting) — the limit, and what a 429 response looks like

5Keeping Docs From Drifting: Contract Testing

The single biggest failure mode of API documentation is silent drift — the code changes, the docs don't, and consumers build against a lie. The fix is to make the schema part of the test suite instead of a static artifact nobody re-checks:

// A contract test: real responses are validated against the OpenAPI schema on every run
import { validateResponseAgainstSchema } from "./openapi-validator";

test("GET /orders/:id matches the documented schema", async () => {
  const response = await request(app).get("/orders/42");
  const result = validateResponseAgainstSchema("GET /orders/{id}", 200, response.body);
  expect(result.valid).toBe(true); // fails the build the moment code and docs disagree
});

Once this exists, a schema/implementation mismatch is a CI failure, not a support ticket filed by a confused consumer weeks later.

6Versioned Documentation

Docs for an API must be versioned exactly like the API itself (see backend/api-design/05-api_versioning) — a consumer pinned to v1 reading v2's documentation will implement against endpoints and shapes that don't exist for them. Most doc-hosting setups publish one rendered doc site per active API version, with the currently-recommended version clearly marked and deprecated versions explicitly labeled with their sunset date.

⚠️ Common Pitfalls

1. Documenting only the 200 response. Consumers building real error handling need every status code the endpoint can actually return, not just the success case.
2. Letting code-first annotations silently omit fields. A forgotten @ApiProperty() (or equivalent) produces a schema that's incomplete, not one that fails to build — nothing forces the gap to surface.
3. No contract tests. Without section 5's validation step, "the docs match the code" is an assumption, not a guarantee, and it erodes the first time someone ships without updating both.
4. Publishing one unversioned doc site. Consumers on an older API version have no way to know the docs they're reading describe a different contract than the one they integrated against.
5. Treating examples as optional. A schema alone (type: string, format: uuid) is technically complete but far slower for a human to act on than one realistic example value.

📋 Quick Reference

OpenAPI/Swagger    machine-readable contract: paths, schemas, responses, auth
Schema-first        write the spec, then implement to match it
Code-first          derive the spec from annotated code
Must document        every param, every realistic status code, auth requirement, example
Contract tests       validate real responses against the schema in CI — catches drift
Versioned docs        one doc site per active API version, deprecated ones labeled

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: api_api_documentation_theory.md · generated by tools/build_lessons.py