5 Min Doc ChallengeSee what's missing in your docs!Start free trial

Glossary

OpenAPI

Definition

OpenAPI is an open, vendor-neutral specification format for describing HTTP APIs — their endpoints, operations, parameters, request and response bodies, and authentication — in a machine-readable YAML or JSON document.

OpenAPI and Swagger

The format began as the Swagger specification. In 2015 it was donated to the OpenAPI Initiative, a project under the Linux Foundation, and renamed. Swagger now refers to a family of tools that work with OpenAPI documents; OpenAPI is the specification itself. Version 3.0 is the most widely deployed; 3.1 aligned its schemas with JSON Schema.

What a spec is used for

Because the document is machine-readable, one file feeds many tools:

  • Reference documentation rendered directly from the spec
  • Client libraries and SDKs generated for several languages
  • Mock servers that answer requests before the real API exists
  • Contract tests that check the implementation returns what the spec promises
  • Gateway and validation configuration that rejects malformed requests

That reuse is the point. One accurate description, many consumers.

A spec can drift too

An OpenAPI document is documentation in a stricter format, and it drifts the same way prose does. A spec written by hand beside the code describes the API as someone believed it to be; endpoints get added without it, and fields change shape. Teams handle this either by generating the spec from the code, or by writing the spec first and testing the code against it. Either works. A spec maintained separately from both does not stay true for long.

What OpenAPI doesn't cover

OpenAPI describes the shape of an HTTP interface. It does not explain why an endpoint exists, which calls to make in what order to finish a task, or what a concept means in your product. It doesn't describe a CLI or the idioms of an SDK, and event-driven interfaces are usually described with a sibling format, AsyncAPI. A spec is the foundation of an API reference, not the whole of a product's documentation.

Related terms

API referenceThe lookup-oriented docs for every endpoint or function, parameter and error.Documentation driftThe widening gap between what the docs describe and what the code does.Shadow API endpointA route that exists in the code and appears in no documentation or inventory.

Go deeper

Questions people ask

Is OpenAPI the same as Swagger?

Not anymore. Swagger was the specification's original name; since 2015 the specification is OpenAPI, and Swagger is the name of a set of tools that work with it.

Do we need an OpenAPI spec to have API docs?

No, but it helps. A spec makes the reference renderable and checkable by tools. Without one, the reference has to be derived from the code some other way.

Can OpenAPI describe GraphQL or gRPC APIs?

Not natively. GraphQL has its own schema language and gRPC uses Protocol Buffers; OpenAPI is built for HTTP APIs described path by path.