Schema-first design, Swagger UI, type generation, contract testing.

OpenAPI Spec — API Documentation, Validation, and Code Generation

OpenAPI Specification (OAS 3.x) is a standard for describing REST APIs in JSON/YAML. Benefits: interactive documentation (Swagger UI, Redoc), client SDK generation (openapi-generator), server stub generation, request/response validation (middleware), and contract testing. Schema-first approach: define the OpenAPI spec before implementing. This enables frontend teams to work against mock servers while the backend is being built.

Interactive Pipeline Flow

UnderstandImplementOptimise

📐 Schema — YAML/JSON spec

OpenAPI YAML spec: openapi: 3.0.3, info: {title, version}, paths: {"/users": {get: {summary, responses: {"200": {content: {"application/json": {schema: {$ref: "#/components/schemas/UserList"}}}}}}}.

Architecture Diagrams

Design the spec first, implement second.

Loading diagram...

Key Design Decisions

📐Design the spec before writing a single line of code

API design decisions are cheapest to change in a YAML file. Once endpoints are in production with clients depending on them, changes are expensive. Spec-first enables parallel frontend/backend with mock servers.

🔧Generate client SDKs from spec, not by hand

Hand-written API clients go stale immediately. openapi-generator generates fully typed clients in any language from the live spec. Regenerate on every spec change — always in sync.

🔗Contract testing catches spec-implementation drift

Documentation says field X is required but code makes it optional. Schemathesis automatically tests your API against the spec and catches these inconsistencies. Run in CI on every PR.

Discussion