OpenAPI: A Complete Guide to the Specification
What the OpenAPI Specification is, how a document is built, why a contract is not the same thing as documentation, and what you get out of the file once it exists.
Your API already has a contract. The question is whether it is written down anywhere a machine can read it, or whether it lives in the implementation, in a wiki page from last year and in the heads of two people.
An OpenAPI document is that contract written down. This guide covers what belongs in the file and how to write the parts that are easy to get wrong. It then covers how to check that the result is both valid and good, and what you can build from it afterwards.
A contract is not documentation
The distinction sounds academic until you watch a team maintain both of them. Documentation describes what an API does, while a contract states what it promises, and only the second of those can be checked by a machine.
That difference is what makes the file worth the effort. A description nobody can verify ages quietly, because there is no moment at which being wrong costs anything. A contract can be validated against the running service, so being wrong surfaces on the next test run rather than in a support ticket six weeks later.
Everything else in this guide follows from that. The file is written for tools first and for people second, which is exactly why people end up trusting it.
What you get from one file
The reason to keep a contract in one place is that so many other things are derived from it rather than written again.
Each of those arrows is a copy you do not maintain. That is also the honest limit of the idea, because anything the document does not say cannot be derived. A document full of untyped objects and missing descriptions generates exactly as little as it contains.
The shape of a document
An OpenAPI document is one object with a small number of top-level fields, and almost everything you write sits under two of them.
The info block names and versions the document, and the servers block lists the base URLs it is reachable at. The paths block holds one entry per route, and each of those holds one entry per HTTP method, which the specification calls an operation. The components block holds the definitions you reference from more than one place. The anatomy chapter walks through all of it with a complete example.
Two of those fields are worth separating right now, because mixing them up causes real confusion. The openapi field at the root names the version of the specification your file is written against, while info.version describes your document. OpenAPI 3.1.1 defines info.version as the version of the OpenAPI document and states that this is distinct from the specification version and from the version of the API being described.
Which version of the specification
Three lines of the specification are in use, and the difference between them is mostly about JSON Schema.
OpenAPI 3.0 uses a modified subset of an old JSON Schema draft, which is where nullable comes from. OpenAPI 3.1 replaced that with JSON Schema 2020-12 and dropped the workarounds. OpenAPI 3.2.0 arrived on 19 September 2025 and added new capabilities on top of 3.1 rather than changing the schema model again. The version chapter covers what actually changed and what a tool has to touch when you upgrade.
The short answer
If you take one rule from this guide, take this one. Write the contract first, keep exactly one copy of it, and derive everything else from that copy rather than maintaining a second description by hand.
The rest of the guide is that rule taken apart.
| Chapter | Answers |
|---|---|
| OpenAPI vs Swagger | Where the two names came from and which one applies to what |
| Anatomy of a document | Every top-level field, with a complete working example |
| 3.0, 3.1 and 3.2 | What each version changed, and what an upgrade costs |
| Schemas | Objects, composition, enums, formats and nullability |
| Parameters, bodies, responses | The three halves of an operation and the mistakes in each |
| Components and reuse | What $ref buys you and when extracting one is premature |
| Validating and linting | Is it valid OpenAPI, and separately, is it any good |
| From collections to contracts | What an importer can infer from examples and what it cannot |
| What you derive | Docs, mocks, tests, monitors, samples, and where generation stops |
| Descriptions an agent can use | The four questions a description has to answer |
Three neighbouring subjects live in other guides. Security schemes are covered in OpenAPI security schemes, and the several things called a version are untangled in OpenAPI versioning. This guide covers how a contract is written down, while API design covers how it is decided in the first place.
In Routebase
Routebase is an OpenAPI editor with the rest of the lifecycle attached. You work on endpoints, schemas and components in a structured designer rather than in raw YAML, and the document is the storage format rather than an export step.
Specifications are authored as OpenAPI 3.0, 3.1 or 3.2, new ones default to 3.2, and every frozen version exports as YAML, JSON, Postman or Insomnia. Existing files come in the same way, so nothing about this is a one-way door. Start with the Endpoints guide in the product documentation, or read on. The API design feature page has the short version of how the designer fits into the rest of the lifecycle.
Frequently asked questions
What is OpenAPI?
OpenAPI is a specification for describing an HTTP API in a single machine-readable document. The document lists the paths, the operations on each path, the inputs each operation takes, the responses it returns and the schemas behind those responses. Because the format is standardised, other tools can read your description and produce documentation, mock servers, tests and client code from it.
Is OpenAPI the same as Swagger?
They share a lineage rather than a meaning. Swagger was the original name of the specification, and version 2.0 was donated to the OpenAPI Initiative at the end of 2015, after which the specification was renamed and continued as OpenAPI 3.0. Today Swagger is a family of tools from SmartBear, so a file is OpenAPI while an editor or a renderer might be Swagger.
What is an OpenAPI document used for?
It is the one description that several tools read instead of each holding its own copy. A reference page can be generated from it, and a mock server can answer from its response schemas. A test runner can assert that the live API still matches it, and a monitor can validate production responses against it. The value comes from having one source rather than five that drift apart.
Should you write OpenAPI in YAML or JSON?
Both are valid and describe the same document, so the choice is about who reads the file. YAML carries comments and produces readable diffs in review, which is why most teams write it that way. JSON is what most tooling emits and consumes, and converting between the two loses nothing except the comments.
Last reviewed by The Routebase Team.