OpenAPI

Updated September 30, 20262 min read

In short

OpenAPI is an open standard for describing HTTP APIs in a YAML or JSON file, so people and tools can understand every endpoint, parameter, and response.

What is OpenAPI?

OpenAPI, formally the OpenAPI Specification (OAS), is a standard format for describing HTTP APIs, mostly REST-style ones, in a machine-readable file written in YAML or JSON. The file lists every endpoint, the HTTP methods it supports, its parameters, request bodies, possible responses, data schemas, and authentication methods. It grew out of the Swagger Specification, which was donated to the OpenAPI Initiative, a Linux Foundation project, in 2015 and renamed; the current major version is 3.

Because the description is structured data, tools can do a lot with it: generate interactive documentation where developers can try requests in the browser, generate client libraries and server code in many languages, validate requests and responses, create mock servers, and run contract tests. Teams either write the OpenAPI file first and build the API to match, called design-first, or generate it from annotations in their code, called code-first.

An OpenAPI document is like the blueprint of a building: builders, inspectors, and electricians can all work from the same drawing without walking through the building itself. It is widely used for public APIs and internal microservices, and many API gateways can import OpenAPI files to configure routes and request validation.

OpenAPI and Swagger are often used as synonyms, but today OpenAPI is the name of the specification, while Swagger refers to a set of tools, such as Swagger UI and Swagger Editor, that work with it. OpenAPI also differs from GraphQL schemas and gRPC .proto files, which describe other styles of API, and a related standard called AsyncAPI describes event-driven, message-based APIs.

Key takeaways

OpenAPI describes HTTP APIs in a standard YAML or JSON document.
It covers endpoints, parameters, request and response schemas, and authentication.
Tools use it to generate docs, client SDKs, server stubs, mock servers, and tests.
OpenAPI is the specification; Swagger is the name of a set of tools that work with it.
Design-first teams write the spec before the code; code-first teams generate it from code.

Example

A minimal OpenAPI 3.1 documentyaml

openapi: 3.1.0
info: { title: Users API, version: 1.0.0 }
paths:
  /users/{id}:
    get:
      summary: Get a user by ID
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses:
        "200":
          description: The user
          content:
            application/json:
              schema: { type: object, properties: { name: { type: string } } }
        "404": { description: No user with that ID }

Readers ask

What is the difference between OpenAPI and Swagger?

OpenAPI is the name of the specification for describing HTTP APIs. Swagger was the specification's original name and is now the name of a set of tools, such as Swagger UI and Swagger Editor, that read and edit OpenAPI files.

Is OpenAPI only for REST APIs?

It is designed for HTTP APIs, which in practice are mostly REST-style APIs. GraphQL, gRPC, and message-based APIs use other formats, such as GraphQL schemas, Protocol Buffers, and AsyncAPI.

Should I write the OpenAPI file by hand or generate it?

Both approaches are common. Writing it first (design-first) helps teams agree on the API before coding, while generating it from code annotations (code-first) keeps it in sync with the implementation automatically.