OpenAPI is a language-agnostic, machine-readable specification for describing HTTP-based RESTful APIs. An OpenAPI document defines available endpoints, operations, parameters, request and response schemas, and authentication mechanisms in a single structured file written in YAML or JSON. It enables automated generation of documentation, client SDKs, server stubs, and validation logic, decoupling an API’s contract from its implementation.
Overview
- OpenAPI emerged from the Swagger specification, which was donated to the OpenAPI Initiative under the Linux Foundation. The specification establishes a common vocabulary so that tooling, services, and humans can understand an API without access to its source code or additional documentation. Versions of the specification have progressively added support for richer schema descriptions, callbacks, links between operations, and reusable components.
Key aspects
- An OpenAPI document is a structured object describing servers, paths, operations, components, and security schemes.
- Schemas are expressed using a superset of JSON Schema, allowing precise validation of request and response payloads.
- Reusable components reduce duplication across endpoint definitions.
- Tooling ecosystems generate interactive documentation, mock servers, client libraries, and contract tests directly from the document.
Applications
- Generating browsable, interactive API reference documentation.
- Producing strongly typed client SDKs across many programming languages.
- Scaffolding server stubs and request/response validation middleware.
- Driving contract testing and API governance in microservice architectures.