Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 4 · Lesson 22 · 4 min read

OpenAPI and Swagger: API Documentation Guide

On this page
  1. Why hand-written API docs go stale
  2. What is OpenAPI? An example spec
  3. Linting an OpenAPI spec with Redocly
  4. What an OpenAPI spec gives you
  5. Design-first vs code-first OpenAPI
  6. Check yourself

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:

YAML
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).

One OpenAPI file drives interactive docs, generated client SDKs, mock servers, request validation and breaking-change checks.
One OpenAPI file drives interactive docs, generated client SDKs, mock servers, request validation and breaking-change checks.

Linting an OpenAPI spec with Redocly

Redocly CLI validates the spec and applies style rules:

Shell
npx @redocly/cli lint openapi.yaml
Code
openapi.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:

Code
  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.