OpenAPI / Swagger Specification

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/

References

• ↗ https://spec.openapis.org/oas/latest.html
• ↗ https://github.com/zircote/swagger-php

Tags

Related Terms