API Documentation

Also Known As

TL;DR

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

Common Misconception

Why It Matters

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

// 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

# 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

Tags

Related Terms