OpenAPI and Swagger: API Documentation Guide
On this page
Why hand-written API docs go stale
Hand-written API docs go stale the week after launch: a field is renamed, a parameter becomes required, and the docs still show the old version. Developers lose trust and start reading your source code, or give up. A machine-readable description that tools validate and generate from fixes this.
What is OpenAPI? An example spec
OpenAPI (formerly Swagger) is the standard format for describing HTTP APIs in YAML or JSON. Version 3.1 aligned its schemas with JSON Schema, and 3.2, released in September 2025, adds features such as streaming responses and the HTTP QUERY method (Swagger blog). 3.1 is still the safe target, because tool support for 3.2 is catching up. One file describes paths, parameters, request and response bodies, errors and security:
openapi: 3.1.0
info:
title: Orders API
version: 1.4.0
servers:
- url: https://api.example.com/v1
security:
- bearerAuth: []
paths:
/orders/{orderId}:
get:
operationId: getOrder
summary: Get one order
parameters:
- name: orderId
in: path
required: true
schema: { type: integer }
responses:
'200':
description: The order.
content:
application/json:
schema: { $ref: '#/components/schemas/Order' }
example: { id: 482, status: paid, total: 42.5, currency: USD, createdAt: '2026-09-07T10:00:00Z' }
'404': { $ref: '#/components/responses/Problem' }
components:
securitySchemes:
bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
schemas:
OrderStatus:
type: string
enum: [pending, paid, shipped, cancelled]
Order:
type: object
required: [id, status, total, currency, createdAt]
properties:
id: { type: integer }
status: { $ref: '#/components/schemas/OrderStatus' }
total: { type: number }
currency: { type: string, pattern: '^[A-Z]{3}$' }
createdAt: { type: string, format: date-time }(The full test file also defines listOrders with cursor pagination and the Problem schema from Day 8.) Reusable pieces live under components and are referenced with $ref.
Read it top to bottom as answers to a client's questions: where is the API (servers), how do I sign in (security), what can I call (paths, one entry per URL and method), what do I send and get back (parameters, responses), and what do those objects look like (components/schemas). operationId gives each operation a name, which code generators turn into method names such as client.getOrder(482).
Linting an OpenAPI spec with Redocly
Redocly CLI validates the spec and applies style rules:
npx @redocly/cli lint openapi.yamlopenapi.yaml: validated in 20ms
Woohoo! Your API description is valid. 🎉
You have 1 warning.(The warning is a rule against example.com server URLs, expected in a sample.) Introduce two typical mistakes, a misspelled $ref and a response missing its required description, and the linter catches both:
40:28 error no-unresolved-refs Can't resolve $ref
54:9 error struct The field `description` must be present on this level.
55:11 error struct Property `summary` is not expected here.
58:23 error no-unresolved-refs Can't resolve $ref
❌ Validation failed with 4 errors and 2 warnings.Run it in CI so a broken spec can't merge. Spectral is another popular linter with custom rule sets.
What an OpenAPI spec gives you
- Interactive documentation (Redoc, Swagger UI, Scalar) generated from the file, always matching it.
- Client SDKs generated for many languages (OpenAPI Generator, Speakeasy, Stainless).
- Mock servers (Prism) so frontend teams can build before the backend exists.
- Request and response validation in the server, against the same schemas.
- Breaking-change detection: tools like oasdiff compare two versions of the spec in CI (Day 23).
Design-first vs code-first OpenAPI
- Schema-first (design-first): write and review the OpenAPI file, then implement. Consumers can review the design before code exists, and parallel work starts on day one.
- Code-first: generate the spec from annotated code (FastAPI, NestJS, Springdoc, ASP.NET). Less duplication, but the design is shaped by implementation.
Either way, the spec in the repository is the source of truth, and CI fails if code and spec disagree. Docs still need humans for the rest: getting-started guides, authentication walkthroughs, and runnable examples for common tasks.
Check yourself
The docs then always match the described API, and the same file drives client SDKs, mock servers, request validation and contract tests. Hand-written docs drift from the code within weeks.
Unresolvable $ref references, a response missing its required description, and an unexpected field. Linting in CI catches these before broken docs or generated SDKs reach consumers.
Consumers can review the API before it's built, and frontend and backend work can proceed in parallel against the agreed contract.
The spec only describes what was built, so design problems are found after implementation, and accidental changes to code silently change the contract.
Validate requests and responses against the spec in tests or middleware, and diff spec changes in CI to flag breaking ones.