# OpenAPI: A Complete Guide to the Specification — Routebase

> 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.

Canonical page: https://routebase.dev/guides/openapi/
Guide overview · 10 chapters · Last reviewed 2026-09-13 · The Routebase Team

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.

_Figure: The contract is written once, and the reference documentation, the mock server, the contract tests, the monitors and the code samples are all projections of it rather than separate copies that somebody keeps in step by hand._

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](/guides/openapi/anatomy-of-an-openapi-document/) 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](/guides/openapi/openapi-3-0-3-1-3-2/) 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](/guides/openapi/openapi-vs-swagger/) | Where the two names came from and which one applies to what |
| [Anatomy of a document](/guides/openapi/anatomy-of-an-openapi-document/) | Every top-level field, with a complete working example |
| [3.0, 3.1 and 3.2](/guides/openapi/openapi-3-0-3-1-3-2/) | What each version changed, and what an upgrade costs |
| [Schemas](/guides/openapi/openapi-schemas/) | Objects, composition, enums, formats and nullability |
| [Parameters, bodies, responses](/guides/openapi/openapi-parameters-request-bodies-and-responses/) | The three halves of an operation and the mistakes in each |
| [Components and reuse](/guides/openapi/openapi-components-and-reuse/) | What `$ref` buys you and when extracting one is premature |
| [Validating and linting](/guides/openapi/validating-and-linting-openapi/) | Is it valid OpenAPI, and separately, is it any good |
| [From collections to contracts](/guides/openapi/importing-postman-and-insomnia-collections/) | What an importer can infer from examples and what it cannot |
| [What you derive](/guides/openapi/what-you-derive-from-openapi/) | Docs, mocks, tests, monitors, samples, and where generation stops |
| [Descriptions an agent can use](/guides/openapi/openapi-descriptions-for-agents/) | The four questions a description has to answer |

Three neighbouring subjects live in other guides. Security schemes are covered in [OpenAPI security schemes](/guides/api-authentication/openapi-security-schemes/), and the several things called a version are untangled in [OpenAPI versioning](/guides/api-versioning/openapi-versioning/). This guide covers how a contract is written down, while [API design](/guides/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.

_Screenshot: The endpoint tree, the operation being edited and a real request against a selected environment sit in one window, so the contract and the check that it holds are never two tools apart._

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](https://docs.routebase.dev/endpoints/) in the product documentation, or read on. The [API design feature page](/api-design/) 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.

## Chapters in this guide

1. [OpenAPI vs Swagger](https://routebase.dev/guides/openapi/openapi-vs-swagger/): Where the two names come from, what changed when Swagger 2.0 became OpenAPI 3.0, which tools still carry the Swagger name, and which file your tooling actually expects.
2. [Anatomy of an OpenAPI Document](https://routebase.dev/guides/openapi/anatomy-of-an-openapi-document/): Every top-level field of an OpenAPI document explained in the order you meet it, with one complete working example and the difference between YAML and JSON.
3. [OpenAPI 3.0, 3.1 and 3.2](https://routebase.dev/guides/openapi/openapi-3-0-3-1-3-2/): What changed when 3.1 adopted JSON Schema 2020-12, what 3.2 added on top, and what a document and its tooling actually have to touch on the way up.
4. [OpenAPI Schemas](https://routebase.dev/guides/openapi/openapi-schemas/): Objects, arrays and primitives, the difference between allOf, oneOf and anyOf, enums that carry meaning, formats, nullability in both dialects, and examples that stay true.
5. [Parameters, Request Bodies and Responses](https://routebase.dev/guides/openapi/openapi-parameters-request-bodies-and-responses/): The four parameter locations and what each one is for, how a request body is described, responses per status code with headers and examples, and the errors most documents leave out.
6. [Components and Reuse](https://routebase.dev/guides/openapi/openapi-components-and-reuse/): What lives under components, how a reference works, when extracting something is worth it and when it is premature, and what changes once a definition is shared across teams.
7. [Validating and Linting OpenAPI](https://routebase.dev/guides/openapi/validating-and-linting-openapi/): Validation answers whether a document is legal OpenAPI and linting answers whether it is any good. What each one catches, which rules find real defects, and how severities decide what blocks a release.
8. [From Collections to Contracts](https://routebase.dev/guides/openapi/importing-postman-and-insomnia-collections/): Why a Postman or Insomnia collection is not an API contract, what an importer can infer from example data and what it cannot, and the work that is left after the import finishes.
9. [What You Derive From OpenAPI](https://routebase.dev/guides/openapi/what-you-derive-from-openapi/): Reference documentation, mock servers, contract tests, monitors and code samples all come out of the same document. What each one needs from it, and where generation stops being useful.
10. [Descriptions an Agent Can Use](https://routebase.dev/guides/openapi/openapi-descriptions-for-agents/): What a coding agent reads out of an OpenAPI document, the four questions a description has to answer, and why the fields people treat as decoration are the ones that decide whether the call succeeds.

---

[Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.