What is OpenAPI in one sentence?

OpenAPI is a standard, machine-readable document that describes a REST API — its endpoints, parameters, schemas, and auth — so that tools can generate documentation, client SDKs, mock servers, and tests from it.

Is OpenAPI the same as Swagger?

Effectively yes, historically. The spec was called Swagger until it was donated to the OpenAPI Initiative in 2015 and renamed OpenAPI. 'Swagger' now refers to the popular tooling (Swagger UI, Swagger Editor) around the spec.

What format is an OpenAPI document?

A single YAML or JSON file. It is human-readable and version-controllable, and most teams keep it in the repo alongside the code it describes.

What can you generate from an OpenAPI spec?

Interactive documentation, typed client SDKs in many languages, server stubs, mock servers, contract tests, and request validation middleware — all from the same source of truth.

Design-first or code-first?

Design-first writes the spec before the code, so teams agree on the contract up front. Code-first generates the spec from annotated code. Both work; design-first tends to produce cleaner, more deliberate APIs.

Glossary · APIs

What is OpenAPI (Swagger)?

OpenAPI is a standard, machine-readable way to describe a REST API in a single YAML or JSON file — every endpoint, parameter, request and response shape, and authentication scheme — so that documentation, client SDKs, mock servers, and tests can all be generated from one source of truth instead of drifting out of sync by hand.

Swagger, renamed

The format began life as Swagger, created in 2011. In 2015 it was donated to a Linux Foundation working group, the OpenAPI Initiative, and the specification itself was renamed OpenAPI. The word "Swagger" survives as the name of the popular tooling built around it — Swagger UI for interactive docs, Swagger Editor for authoring. So when people say "the Swagger file," they almost always mean an OpenAPI document.

What lives in the document

An OpenAPI file describes paths (the endpoints), the operations on each (GET, POST, and so on), the parameters and request bodies they accept, the responses and status codes they return, reusable schema components, and the security schemes — API keys, OAuth2, or bearer JWT tokens. It is the complete contract of a REST API, written down in a form both humans and machines can read.

Why it is worth the effort

The payoff is automation, end to end. From one spec you can render always-current interactive documentation, generate typed client SDKs in a dozen languages, stand up a mock server before the backend exists, validate incoming requests against the schema, and run contract tests that fail the build when the implementation drifts from the contract. The spec stops being paperwork and becomes a tool that does real work across the whole API lifecycle.

Design-first vs code-first

Teams take two routes. Design-first means writing the OpenAPI spec before any code, so consumers and providers agree on the contract up front and frontend work can start against a mock immediately. Code-first means generating the spec from annotations in the implementation. Design-first tends to produce more deliberate, consistent APIs because the contract is a decision rather than a byproduct — though it only stays honest if you also test the running API against the spec.

The drift trap

The single biggest failure mode is a spec that no longer matches reality. Hand-maintained documentation rots the moment someone ships a change and forgets to update the file — and a lying spec is worse than none, because integrators trust it. The defense is to wire the spec into CI: validate requests and responses against it, generate clients from it, and break the build when code and contract diverge. That is also where API versioning discipline pays off — the spec makes breaking changes visible.

At QUANT LAB

We treat the OpenAPI document as a first-class deliverable, not an afterthought. On our API development engagements the spec lives in the repo, drives the generated client SDKs and the published docs, and is enforced in CI so the contract cannot silently drift from the code. A client integrating with the API gets accurate documentation and a typed SDK on day one — which is what turns a REST API from a support burden into a product people enjoy building on.

Long-form deep-dives that use this term

All posts

Related terms

Want a spec-driven API?

We design APIs spec-first, with generated SDKs and docs and contract tests that keep them honest. Book a 30-minute call.

API development