OpenAPI / Swagger Specification

The OpenAPI Specification (OAS, formerly Swagger) is the industry standard for describing REST APIs in a machine-readable format. An OpenAPI document defines endpoints (paths and operations), request parameters and bodies, response schemas, authentication schemes, and example payloads using YAML or JSON. This single source of truth can be used to generate documentation, client SDKs, server stubs, mock servers, and validation middleware, ensuring consistency between the specification and the implementation.

OpenAPI 3.1 (the latest version) aligns its schema definition with JSON Schema 2020-12, enabling full JSON Schema compatibility. Key sections include info (API metadata), servers (environment URLs), paths (endpoints with operations), components (reusable schemas, parameters, responses, security schemes), and security (authentication requirements). Well-structured specs use $ref extensively to reference shared components, keeping the document DRY and maintainable.

The spec-first (design-first) approach writes the OpenAPI document before implementation and generates server stubs from it, ensuring the API contract is deliberate. The code-first approach generates the OpenAPI spec from annotated code (e.g., using tsoa, NestJS Swagger, or FastAPI). Both approaches benefit from CI-based spec validation using tools like Spectral for linting, oasdiff for breaking change detection, and Prism for contract testing against the spec.