OpenAPI and Swagger
You've written a REST API. Now someone wants docs, and someone else wants a client library, and a third person keeps calling your endpoint with the wrong field names. You could write all that by hand, three times, and watch it drift out of date the moment you ship the next endpoint. Or you could describe the API once, in a file, and let machines do the rest. That file is an OpenAPI document, and this guide is about treating it as the single source of truth instead of an afterthought.
How to read this
Read in order. Phase 1 builds the mental model: what OpenAPI actually is, why "Swagger" and "OpenAPI" are two names for overlapping things, and why a machine-readable contract changes how you work. Phase 2 is the everyday core: writing a spec by hand, generating docs and clients, and choosing between design-first and code-first. Phase 3 is production reality: validation, mocking, contract tests, versioning, and the gotchas that bite teams who treat the spec as decoration.
The phases
- Phase 1: The Contract, Not the Docs - what OpenAPI is and why a machine-readable spec exists.
- Phase 2: Writing and Generating From the Spec - author a spec, render docs, generate clients, pick a workflow.
- Phase 3: The Spec at Work in Production - validation, mocking, contract tests, versioning, and the traps.