What is OpenAPI?
OpenAPI is a standard format for describing a REST API: its endpoints, inputs, outputs, and errors, in a machine-readable document. From that one description you get interactive docs, client SDKs, and request validation — all generated, all in sync with the spec.
Why it matters
An undocumented API is one nobody can use without reading your source. OpenAPI makes the contract explicit and tooling-friendly, so consumers integrate faster and with fewer support questions. For any API other teams or the public touch, this is the professional baseline.
What to learn
- The shape of an OpenAPI document: paths, operations, schemas
- Describing request bodies, parameters, and responses
- Reusable components and
$ref - Generating interactive docs with Swagger UI
- Generating client SDKs from the spec
- Spec-first vs code-first workflows
- Keeping the spec in sync with the implementation
Common pitfall
Letting the spec drift from the real API. Hand-written docs that lag behind the code are worse than none, because consumers trust them and get burned. Generate the spec from code, or validate the running API against the spec in CI, so the two cannot silently disagree.
Resources
Primary (free):
- OpenAPI — Specification · docs
- Swagger — OpenAPI guide · docs
- Redocly — OpenAPI starter · docs
Practice
Write an OpenAPI document for the CRUD API you built earlier: describe each path, its parameters, request body schema, and responses. Load it into Swagger UI and try a request from the generated docs. Done when the interactive docs let someone call your API without reading your code.
Outcomes
- Describe an endpoint's inputs, outputs, and errors in OpenAPI.
- Reuse schemas with components and references.
- Generate interactive docs and a client SDK from the spec.
- Keep the spec and the implementation from drifting apart.