{
    "slug": "api_documentation",
    "term": "API Documentation",
    "category": "api_design",
    "difficulty": "intermediate",
    "short": "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.",
    "long": "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.",
    "aliases": [
        "OpenAPI",
        "Swagger",
        "API docs",
        "API specification"
    ],
    "tags": [
        "api-design",
        "documentation",
        "php"
    ],
    "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."
    ],
    "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."
    ],
    "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."
    ],
    "related": [
        "rest_constraints",
        "api_versioning",
        "api_mocking",
        "api_contract_testing"
    ],
    "prerequisites": [
        "openapi",
        "api_design",
        "api_versioning"
    ],
    "refs": [
        "https://spec.openapis.org/oas/v3.1.0"
    ],
    "bad_code": "// Undocumented API:\n// GET /api/users/{id}\n// Returns... something\n// Authentication: required (how? nobody knows)\n// Errors: possible (what errors? unclear)\n// Rate limits: exist (how many? unknown)\n// Developer experience: frustrating",
    "good_code": "# openapi.yaml:\npaths:\n  /api/users/{id}:\n    get:\n      summary: Get user by ID\n      security: [{BearerAuth: []}]\n      parameters:\n        - name: id\n          in: path\n          required: true\n          schema: {type: integer, example: 42}\n      responses:\n        200:\n          content:\n            application/json:\n              example:\n                {id: 42, name: Alice, email: alice@example.com}\n        404:\n          content:\n            application/json:\n              example:\n                {error: USER_NOT_FOUND, message: No user with id 42}",
    "example_note": "The 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.",
    "quick_fix": "Use OpenAPI 3.x and generate it from PHP attributes (nelmio/api-doc-bundle, swagger-php) rather than writing it manually — the code and docs stay in sync automatically",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-16",
    "updated": "2026-03-31",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/api_documentation",
        "html_url": "https://codeclaritylab.com/glossary/api_documentation",
        "json_url": "https://codeclaritylab.com/glossary/api_documentation.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[API Documentation](https://codeclaritylab.com/glossary/api_documentation) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/api_documentation"
            }
        }
    }
}