LFThe OpenAPI Specification (OAS) is the most widely adopted standard for describing RESTful APIs in a machine-readable format. It enables developers to define the complete interface of an HTTP API — endpoints, operations, parameters, authentication, and response schemas — in a single YAML or JSON document. This definition can then drive automated documentation, client and server code generation, testing, and API governance workflows across the software industry.
Background
The specification originated in 2011 as the Swagger Specification, created by Tony Tam at Wordnik to solve the practical problem of keeping API documentation synchronized with implementation. Swagger quickly gained popularity alongside its open-source tooling (Swagger UI, Swagger Codegen, Swagger Editor). In 2015, SmartBear Software acquired the Swagger brand and donated the specification itself to the Linux Foundation, where it was renamed the OpenAPI Specification under the newly formed OpenAPI Initiative (OAI). Founding members of the OAI included Google, IBM, Microsoft, and PayPal, signaling broad industry commitment to the standard.
Purpose & Scope
An OpenAPI document describes the surface area of an HTTP API: what endpoints are available, what operations each supports (GET, POST, PUT, DELETE, etc.), what parameters and request bodies they accept, what responses they return, and what authentication methods they require. The specification uses JSON Schema for defining data models, enabling detailed validation of request and response payloads. This single source of truth eliminates the drift between documentation and implementation that plagues many API programs.
Key Concepts
| Concept | Description |
|---|---|
| Paths | URL patterns representing API endpoints |
| Operations | HTTP methods (GET, POST, etc.) available on each path |
| Parameters | Inputs to operations (path, query, header, cookie) |
| Request Body | Structured content sent with POST/PUT/PATCH operations |
| Responses | Expected outputs including status codes and schemas |
| Components | Reusable schemas, parameters, responses, and security definitions |
| Security | Authentication and authorization schemes (OAuth2, API key, etc.) |
Serializations & Technical Formats
OpenAPI documents can be authored in either YAML or JSON, with YAML being the more common choice for human authoring due to its readability. The specification itself is defined as a JSON Schema, and OAS 3.1 (released February 2021) achieved full alignment with JSON Schema Draft 2020-12, resolving longstanding incompatibilities. API definitions are typically stored as a single file or split across multiple files using JSON Reference ($ref).
Governance & Maintenance
The OpenAPI Initiative operates under the Linux Foundation with a Technical Steering Committee (TSC) that guides specification development. The specification follows semantic versioning and evolves through a public RFC process on GitHub. OAS 3.0 (July 2017) was the first release under the OpenAPI name, introducing a clearer structure with components and improved security definitions. OAS 3.1 brought full JSON Schema compatibility. The "Swagger" name persists in the tooling ecosystem (Swagger UI, SwaggerHub) but no longer refers to the specification itself.
Notable Implementations
The OpenAPI ecosystem is extensive. Swagger UI and Redoc render interactive documentation from OAS files. Code generators (OpenAPI Generator, Swagger Codegen) produce client SDKs and server stubs in dozens of programming languages. API gateways (Kong, AWS API Gateway, Azure API Management) import OAS definitions for routing and validation. Testing tools (Postman, Dredd, Schemathesis) use OAS files for contract testing. Cloud platforms including AWS, Google Cloud, and Azure accept OpenAPI definitions for API deployment and management.
Related Standards
No directly related standards are currently indexed.