A spec, not just docs
OpenAPI is a standard format for describing a REST API in a structured file. It lists every endpoint, its parameters, request and response shapes, and error codes in a way both humans and tools can read.
Why it is more than prose
Because the spec is machine readable, it powers a whole toolchain from one source of truth.
- Generate interactive documentation where developers try calls in a browser.
- Generate client and server stubs in many languages.
- Drive contract tests that verify the running API matches the spec.
Two ways to keep it honest
- Spec first: write the OpenAPI document, then implement against it. The contract is agreed before code.
- Code first: derive the spec from annotations in the code. Less upfront design, but the spec can drift if annotations lag.
Whichever direction you choose, the win is that documentation, code, and tests share one authoritative description rather than drifting apart.
Key idea
OpenAPI is a machine readable contract that generates docs, client code, and tests from a single source of truth.