Stop 09 · API DesignTopics · 9/12

API Documentation (Swagger/OpenAPI)

In short

If the only way to learn your API is reading your code, nobody will use it properly. An OpenAPI file describes every endpoint in YAML, and tools turn it into docs, tests and client code.

The OpenAPI specification (formerly Swagger) describes your API's endpoints, parameters and responses in a machine-readable format, powering interactive docs and client generation.

The blob character matches a diagram in a big manual to a washing machine knob.

Think of it like this

The washing machine manual

A good manual shows each knob, what it accepts and what happens when you turn it. You never open the machine to find out. An OpenAPI spec is the manual for your API: every endpoint, field and response, written so both people and tools can read it.

Watch it happen

One spec, many uses

Write spec

Lint

Swagger UI

Gen client

Contract

1/5You describe GET /orders/{id}, its parameters and its 200 and 404 responses in openapi.yaml.

The big ideas

What you need to know

One file, many uses

Docs, mock servers, client SDKs and request validation can all come from the same openapi.yaml.

Swagger is the old name

Swagger 2.0 was renamed OpenAPI from version 3. Today Swagger mostly means the tools, like Swagger UI.

Reuse with components

Define an Order schema once under components and point to it with $ref wherever it appears.

Spec-first or code-first

Write YAML first and build to it, or generate it from code. Either way, keep it in git with the code.

See it in code

Walk through the code

yaml

1openapi: 3.1.02info: { title: Orders API, version: 1.0.0 }3paths:4  /orders/{id}:5    get:6      summary: Get one order7      parameters:8        - { name: id, in: path, required: true, schema: { type: integer } }9      responses:10        "200":11          description: The order12          content:13            application/json:14              schema: { $ref: "#/components/schemas/Order" }15        "404":16          description: No order with that id

1/3Which OpenAPI version this is, plus the API's name and version.

The Order schema would live under components.schemas, left out here to keep it short. Paste a full file into editor.swagger.io to see live docs.

Save yourself the pain

Common mistakes

Oops

Writing the spec once and never touching it again.

Do this instead

Docs that lie are worse than no docs. Validate responses against the spec in tests or CI so drift fails the build.

Oops

Leaving out error responses and examples.

Do this instead

Document 400, 401 and 404 too, with example bodies. Errors are what integrators struggle with most.

Your mission

Describe your own endpoint

~30 min

Quick check

What is Swagger UI today?

Go deeper

1Write an OpenAPI spec for a few endpoints of an API you've built.
2Use Swagger UI to generate interactive, testable docs from your spec.
3Learn how tools can auto-generate a typed API client from an OpenAPI spec.