The OpenAPI Specification is a standard for describing HTTP APIs in a machine-readable format that enables both humans and computers to discover and understand service capabilities without access to source code or additional documentation.
The specification solves the problem of API discoverability and integration by defining a programming language-agnostic interface description format. It allows consumers to understand and interact with remote services with minimal implementation logic, removing guesswork from API consumption. OpenAPI documents are represented in YAML or JSON and can be produced statically or generated dynamically from applications. The specification supports use cases including interactive documentation, code generation for documentation and clients, and test case automation.
Developers should adopt the OpenAPI Specification when they need to document HTTP APIs in a standardized, machine-readable way that facilitates tooling and automation. It suits projects where API discoverability, client generation, and automated testing are priorities. The specification does not require rewriting existing APIs or binding software to a service; it simply requires describing the service's capabilities in OpenAPI structure. It is designed to support both design-first and code-first development approaches. The specification focuses on HTTP APIs and REST services, though it does not attempt to cover every possible style of HTTP API.
The project is maintained as a community-driven specification within the OpenAPI Initiative, a Linux Foundation Collaborative Project. Development follows a formal contributing process documented in the repository's guidelines. The specification is versioned, with all published versions maintained as Markdown sources in the repository alongside release notes and release candidate versions. The project maintains a curated list of implementations showing how developers can create, present, and use OpenAPI definitions.
