Glossary · 2 · Developer SDKs and APIs
OpenAPI Specification
Also known as: OAS, OpenAPI, Swagger Specification
In software engineering, the OpenAPI Specification (OAS) is a programming-language-agnostic standard for describing HTTP APIs in a machine-readable document, written in JSON or YAML, that lists the operations, parameters, request and response bodies, data schemas and security schemes of an API.
- Developer SDKs
- Standards
In one sentence
The OpenAPI Specification describes HTTP APIs in a machine-readable JSON or YAML document used for documentation, testing and SDK generation.
Example
An API team publishes an OpenAPI document for its order service; the reference pages of the developer portal and the client libraries for three languages are generated from the same file.
How it applies
- Developer SDKs: An OpenAPI document is a common input for automatic code generation of client libraries, server stubs and mock servers. It acts as the interface definition of a REST API and, when it is kept under review, as part of its interface contract.
- Documentation: Reference documentation is rendered from the same document, so descriptions, examples and parameter tables stay in step with the API. Conceptual guides, tutorials and error handling still have to be written; a generated reference does not explain why or when to call an operation.
- Platform SDKs: Platforms publish OpenAPI descriptions of their extension and administration APIs, and some describe their outgoing callbacks and webhooks in the same document.
- Versioning: The API version in the document and the version of the specification it is written in are different numbers. API changes are tracked with semantic versioning or a similar policy; the specification version tells tools how to read the file.
- Validation: Requests and responses can be checked against the document's schemas (a form of schema validation). A valid description does not prove that the implementation behaves as described.
OpenAPI vs. Swagger
The OpenAPI Specification is based on the Swagger 2.0 specification, which SmartBear Software donated in 2015; since then it has been developed by the OpenAPI Initiative, a Linux Foundation project. “Swagger” today names a family of tools, while “OpenAPI” names the specification. As of October 11, 2026, the latest published version is 3.2.1 (September 10, 2026); the 3.0 and 3.1 lines are still widely used.