OpenAPI

OpenAPI is a standard format for describing RESTful HTTP APIs. Formerly known as Swagger, it defines a structured document, written in YAML or JSON, that captures an API's endpoints, parameters, request and response schemas, authentication, and examples.

How It Works

An OpenAPI document declares paths and the operations available on each, along with the data models used in requests and responses. Schemas are expressed using a subset of JSON Schema. Because the description is machine-readable, a rich ecosystem of tooling consumes it: interactive documentation viewers, client SDK and server stub generators, request validators, mock servers, and contract tests.

Teams adopt one of two workflows. In design-first, the specification is authored before implementation and serves as the agreed contract. In code-first, the document is generated from annotations in the source code. Both keep a single source of truth for the API surface.

Why It Matters

A shared, precise contract reduces miscommunication between API producers and consumers. Front-end and back-end teams can work in parallel against the same definition, generate type-safe clients, and catch breaking changes automatically in continuous integration.

OpenAPI does not describe every API style. It targets REST-like HTTP APIs; gRPC uses Protocol Buffers and GraphQL uses its own schema language. Even so, OpenAPI remains the dominant interface definition language for HTTP APIs and a key artifact in API governance and lifecycle management.

Related Terms

OpenAPI describes REST APIs, relies on JSON and JSON Schema, and is contrasted with GraphQL schemas and Protocol Buffers as alternative contracts.