OpenAPI / Swagger Specification
debt(d7/e7/b5/t5)
Closest to 'only careful code review or runtime testing' (d7). Spectral can lint an existing spec for structural issues, but the core misuse patterns — spec drifting from implementation, missing error schemas, no runtime validation — are not caught by linting tools alone. The absence of an OpenAPI spec, or a spec that contradicts the actual implementation, is typically only discovered through manual code review, integration tests, or when consumers hit undocumented behaviour in production.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix describes a broad adoption task: defining the API with OpenAPI 3.x, wiring validation middleware, and generating client SDKs. Remediating drift (docs written after the fact, missing $refs, missing error schemas, absent runtime validation) requires touching API route definitions, middleware configuration, schema libraries, and potentially CI pipelines across the codebase — well beyond a single-file fix.
Closest to 'persistent productivity tax' (b5). OpenAPI applies to web/API contexts. A well-adopted spec becomes load-bearing (drives codegen, mocking, contract testing), but the misuse patterns (manual docs, spec drift, no validation) impose an ongoing tax on every change: developers must keep docs in sync, resolve drift, and manage the gap between spec and reality — slowing multiple work streams without necessarily defining the system's shape.
Closest to 'notable trap' (t5). The misconception is clearly documented: developers treat OpenAPI as static documentation rather than a living, tooling-driving artifact. This is a widely encountered gotcha — most developers eventually learn that the real value is in codegen, contract testing, and runtime validation, not just readable docs. It's a notable but well-known trap, not one that catastrophically contradicts developer intuitions from other ecosystems.
Also Known As
TL;DR
Explanation
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.
Common Misconception
Why It Matters
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.
Code Examples
# OpenAPI with no error schemas — consumers can't handle errors:
paths:
/users/{id}:
get:
responses:
'200':
content:
application/json:
schema: {$ref: '#/components/schemas/User'}
# Missing 404, 422, 500 schemas — errors undocumented# OpenAPI 3.0 spec (openapi.yaml)
openapi: 3.0.3
info:
title: Order API
version: '2.0'
paths:
/orders:
post:
summary: Place an order
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [user_id, items]
properties:
user_id: { type: integer }
items:
type: array
items:
type: object
required: [product_id, quantity]
properties:
product_id: { type: integer }
quantity: { type: integer, minimum: 1 }
responses:
'201': { description: Order created }
'422': { description: Validation error }
# Generate PHP client:
$ openapi-generator generate -i openapi.yaml -g php -o client/