The OpenAPI Specification (OAS) is a standard for describing HTTP APIs in a machine-readable form. As the specification itself states, it “defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.” An OpenAPI document, written in JSON or YAML, lists a service’s endpoints, the operations available on each, the parameters and request bodies they accept, the responses they return, and the schemas of the data involved.
The format began life as Swagger, created by Tony Tam at Wordnik to document and test the company’s REST API. Swagger grew into a widely used toolset, and in 2015 the specification was donated to a newly formed OpenAPI Initiative, a Linux Foundation collaborative project backed by a consortium of companies. The specification was renamed the OpenAPI Specification, while the name Swagger continued to live on in the surrounding tooling. The official specification sources are maintained in the open at the OAI/OpenAPI-Specification repository on GitHub.
OpenAPI’s value comes from the ecosystem of tools that consume its documents. From a single OpenAPI description, developers can generate interactive API documentation, server stubs and client SDKs in many languages, request validators, mock servers, and contract tests. This turns the API description into a single source of truth that keeps documentation, code, and behavior aligned, and it makes APIs discoverable in a uniform way across organizations.
The specification has evolved through several major versions. OpenAPI 2.0 corresponds to the original Swagger 2.0 format, while the 3.x line, beginning with 3.0 in 2017 and continuing through later 3.1 and 3.2 releases, reorganized and extended the format with richer schema support, reusable components, and improved alignment with JSON Schema. Each version is published as a normative document on the OpenAPI Initiative’s specification site.
By formalizing how REST-style APIs are described, OpenAPI became the de facto standard for API design and documentation in the web era, sitting alongside the REST architectural style and JSON as one of the foundations of modern web integration. Its design-first workflow, where teams agree on an OpenAPI contract before writing code, reshaped how distributed systems and microservices expose and consume one another’s interfaces.