OpenAPI Specification
Maintained by the OpenAPI Initiative (Linux Foundation)
The OpenAPI Specification is a standard, language-agnostic format for describing the structure of a REST API, including its endpoints, request and response schemas, parameters, and authentication methods, in a machine-readable document,…
Definition
The OpenAPI Specification is a standard, language-agnostic format for describing the structure of a REST API, including its endpoints, request and response schemas, parameters, and authentication methods, in a machine-readable document, typically written in YAML or JSON. It grew out of the earlier Swagger specification and is now maintained by the OpenAPI Initiative, enabling tools to generate documentation, client SDKs, and test suites automatically from a single source of truth.
Overview
Documenting a REST API by hand, in prose or wiki pages, tends to drift out of sync with the actual implementation as endpoints change, and it gives tooling nothing structured to work with for generating clients or validating requests. The OpenAPI Specification addresses this by defining a formal schema for describing an API's surface, its paths, operations, parameters, request bodies, response shapes, and security schemes, as a single machine-readable document that both humans and tools can consume, keeping documentation and tooling aligned with a canonical description rather than scattered prose. Mechanically, an OpenAPI document is typically a YAML or JSON file structured around a set of top-level sections: general API metadata, a list of paths and the operations available on each, reusable schema definitions for request and response bodies, and security scheme definitions describing how clients authenticate. Because these schemas are formally typed, using a dialect closely related to JSON Schema, a wide ecosystem of tooling can consume the same document to render interactive documentation, generate client libraries in many languages, validate incoming requests against the declared schema, or even scaffold server-side route handlers. OpenAPI differs from JSON:API in what it addresses: OpenAPI is a description format that documents whatever API shape a team has designed, while JSON:API is itself a prescriptive response format specification; an API can use both together, with an OpenAPI document describing an API that happens to follow JSON:API conventions. OpenAPI also differs from GraphQL's introspection system, which serves a similar documentation purpose but is built into GraphQL itself and queried at runtime rather than authored as a separate static document. In practice, teams write or generate OpenAPI documents alongside their REST APIs to power interactive documentation portals like Swagger UI or Redoc, to auto-generate typed client SDKs for multiple programming languages from a single spec, and to validate API contracts in continuous integration pipelines, catching breaking changes before they reach production. API gateways and mock server tools also consume OpenAPI documents directly to route or simulate traffic. The specification's main limitation is that it describes an API's shape rather than enforcing it inherently; a hand-maintained OpenAPI document can still drift from the actual implementation unless teams generate it directly from code annotations or enforce contract testing against it. Very large, deeply nested APIs can also produce sprawling OpenAPI documents that become difficult to maintain by hand, pushing teams toward code-first generation tools rather than writing the specification manually from scratch.
Specification
- Describes REST API endpoints, parameters, and schemas in a machine-readable document
- Typically authored in YAML or JSON format
- Uses a JSON Schema-related dialect for typed request and response definitions
- Documents authentication and security schemes for an API
- Powers interactive documentation tools like Swagger UI and Redoc
- Enables automatic generation of client SDKs in multiple languages
- Evolved from and superseded the earlier Swagger specification