When should you NOT use API Documentation?

Do not auto-generate docs from code alone without human-written descriptions — generated summaries are often cryptic or wrong. Avoid keeping docs in a separate repo from the API — they drift out of sync; treat docs as part of the same deployment pipeline.

When is API Documentation the right choice?

Document every public or partner API with OpenAPI — it enables code generation, mock servers, and contract testing from a single source. Write documentation before implementation (design-first) to catch interface problems when they are cheap to fix. Include authentication examples, error response schemas, and rate limit behaviour — these are the most common gaps that block integrators.

← Back to glossary

API Documentation

API Design Intermediate

debt(d7/e3/b3/t5)

d7 Detectability Operational debt — how invisible misuse is to your safety net

Closest to 'only careful code review or runtime testing' (d7) — missing or drifting docs aren't caught by swagger-php or nelmio-api-doc unless contract tests exist; usually noticed in review or by integrator complaints.

e3 Effort Remediation debt — work required to fix once spotted

Closest to 'simple parameterised fix' (e3) — quick_fix is to add OpenAPI annotations via swagger-php/nelmio-api-doc attributes across endpoints, a patterned fix per route rather than one-line.

b3 Burden Structural debt — long-term weight of choosing wrong

Closest to 'localised tax' (b3) — applies_to is web/api context; documentation tooling adds annotation maintenance to controller layer but doesn't shape the whole system.

t5 Trap Cognitive debt — how counter-intuitive correct behaviour is

Closest to 'notable trap' (t5) — misconception that auto-generated docs equal good docs is a documented gotcha; devs eventually learn that examples, edge cases, and rationale matter beyond schema generation.

About DEBT scoring → scored by claude-opus-4-7 · 2026-05-06 · reviewed by human

Also Known As

OpenAPI Swagger API docs API specification

TL;DR

OpenAPI/Swagger for REST APIs, Postman collections for explorability, and Stoplight for design-first workflows — good API docs are the product's user interface for developers.

Explanation

API documentation tools: OpenAPI 3.x (YAML/JSON spec that generates interactive docs via Swagger UI or Redoc), Postman (share runnable collections with examples), Stoplight (design-first — write the spec before the code), and API Blueprint. PHP generators: zircote/swagger-php (annotations/attributes), dedoc/scramble (automatic from route analysis). Good API docs include: authentication details, request/response examples, error codes with meaning, rate limit information, and a changelog. The OpenAPI spec also enables code generation, contract testing, and mock servers.

Watch Out

⚠ OpenAPI specs without example values and error schemas document the happy path only — integrators encounter the undocumented edge cases in production.

Common Misconception

✗ Auto-generated docs from code are as good as hand-written docs — generated docs reflect what the API does, but good documentation explains why, includes real-world examples, and describes edge cases that are not obvious from the code.

Why It Matters

Poor API documentation is the most common reason developers choose a competitor's API — a developer who cannot figure out how to make their first successful request in 15 minutes will look elsewhere.

Common Mistakes

No request/response examples — developers need to see a working example, not just field definitions.
Generic error descriptions — '400 Bad Request' is useless; 'email must be a valid email address' is actionable.
Documentation that drifts from the implementation — generate from code or use contract testing.
No authentication example — showing a complete working curl command is worth more than paragraphs of text.

Avoid When

Do not auto-generate docs from code alone without human-written descriptions — generated summaries are often cryptic or wrong.
Avoid keeping docs in a separate repo from the API — they drift out of sync; treat docs as part of the same deployment pipeline.

When To Use

Document every public or partner API with OpenAPI — it enables code generation, mock servers, and contract testing from a single source.
Write documentation before implementation (design-first) to catch interface problems when they are cheap to fix.
Include authentication examples, error response schemas, and rate limit behaviour — these are the most common gaps that block integrators.

Code Examples

💡 NoteThe bad endpoint has no documented auth method, response shape, or error codes; a developer integrating it must read source or trial-and-error — the fix provides a full OpenAPI definition.

✗ Vulnerable

// Undocumented API:
// GET /api/users/{id}
// Returns... something
// Authentication: required (how? nobody knows)
// Errors: possible (what errors? unclear)
// Rate limits: exist (how many? unknown)
// Developer experience: frustrating

✓ Fixed

# openapi.yaml:
paths:
  /api/users/{id}:
    get:
      summary: Get user by ID
      security: [{BearerAuth: []}]
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: integer, example: 42}
      responses:
        200:
          content:
            application/json:
              example:
                {id: 42, name: Alice, email: alice@example.com}
        404:
          content:
            application/json:
              example:
                {error: USER_NOT_FOUND, message: No user with id 42}

References

https://spec.openapis.org/oas/v3.1.0