OpenAPI Specification

OpenAPI is a YAML or JSON file that describes an HTTP API in a format machines can read: every path and method, the parameters, the request and response schemas, the auth scheme, the error shapes. It used to be called Swagger, which is why people still say 'send me the swagger file' long after the format moved on and kept moving: 2.0, then 3.0, 3.1, and later releases in the 3.x line. Version matters less than compatibility, so check which one your generator, validator, and docs renderer actually accept before you commit to one.

The payoff is tooling. One file gives you rendered docs (Swagger UI, Redoc, Scalar), a typed client in almost any language (openapi-typescript, orval, openapi-generator), a mock server to code against before the backend exists (Prism), and request validation in the middle of your stack. If a vendor publishes a spec, generate the client instead of hand-writing fetch calls; if you publish an API, the spec is the cheapest documentation you will ever maintain.

The failure mode is drift. A spec written by hand in a separate file quietly lies about the API within two sprints. Generate it from the code (Zod plus a route builder, FastAPI, tRPC adapters, decorators) or test the running API against it in CI, so the file cannot disagree with reality without something turning red.