{
    "slug": "openapi",
    "term": "OpenAPI / Swagger Specification",
    "category": "architecture",
    "difficulty": "intermediate",
    "short": "A machine-readable YAML/JSON description of a REST API — enabling auto-generated documentation, client SDKs, mock servers, and contract testing.",
    "long": "OpenAPI (formerly Swagger) is the standard for describing REST APIs in YAML or JSON: endpoints, parameters, request/response schemas, authentication methods, and error codes. An OpenAPI spec enables: Swagger UI interactive documentation, auto-generated client SDKs, contract testing (Dredd, Schemathesis), and mock servers for frontend development against a not-yet-built backend. PHP tools include zircote/swagger-php (annotation-based generation from docblocks), API Platform (spec-first approach), and league/openapi-psr7-validator for runtime request validation. Design-first (write the spec before the code) consistently produces better-structured APIs than code-first generation.",
    "aliases": [
        "OpenAPI Specification",
        "Swagger",
        "OAS",
        "API spec"
    ],
    "tags": [
        "architecture",
        "api",
        "documentation",
        "tooling"
    ],
    "misconception": "OpenAPI is just API documentation. An OpenAPI spec also drives code generation for clients and servers, automated contract testing, mock servers, and validation middleware — treating it as living documentation that drives tooling is far more valuable than static docs alone.",
    "why_it_matters": "OpenAPI (Swagger) is the standard for describing REST APIs — a machine-readable spec enables auto-generated docs, client SDKs, and contract testing, making the API a verifiable artifact not just documentation.",
    "common_mistakes": [
        "Writing OpenAPI docs manually after the fact — they drift from the implementation immediately.",
        "Not using $ref for shared schemas — duplicate schema definitions diverge over time.",
        "Missing error response schemas — consumers cannot handle errors programmatically without them.",
        "Not validating requests against the OpenAPI spec at runtime — the spec and code can contradict each other."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "rest",
        "api_design",
        "api_versioning",
        "contract_testing"
    ],
    "prerequisites": [
        "api_documentation",
        "api_design",
        "api_contract_testing"
    ],
    "refs": [
        "https://spec.openapis.org/oas/latest.html",
        "https://github.com/zircote/swagger-php"
    ],
    "bad_code": "# OpenAPI with no error schemas — consumers can't handle errors:\npaths:\n  /users/{id}:\n    get:\n      responses:\n        '200':\n          content:\n            application/json:\n              schema: {$ref: '#/components/schemas/User'}\n        # Missing 404, 422, 500 schemas — errors undocumented",
    "good_code": "# OpenAPI 3.0 spec (openapi.yaml)\nopenapi: 3.0.3\ninfo:\n  title: Order API\n  version: '2.0'\npaths:\n  /orders:\n    post:\n      summary: Place an order\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              type: object\n              required: [user_id, items]\n              properties:\n                user_id: { type: integer }\n                items:\n                  type: array\n                  items:\n                    type: object\n                    required: [product_id, quantity]\n                    properties:\n                      product_id: { type: integer }\n                      quantity:   { type: integer, minimum: 1 }\n      responses:\n        '201': { description: Order created }\n        '422': { description: Validation error }\n\n# Generate PHP client:\n$ openapi-generator generate -i openapi.yaml -g php -o client/",
    "quick_fix": "Define your API with OpenAPI 3.x — generate interactive docs with Swagger UI, validate requests/responses with middleware, and generate client SDKs automatically",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/openapi",
        "html_url": "https://codeclaritylab.com/glossary/openapi",
        "json_url": "https://codeclaritylab.com/glossary/openapi.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": "[OpenAPI / Swagger Specification](https://codeclaritylab.com/glossary/openapi) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/openapi"
            }
        }
    }
}