Deutsch
Agent protocols

OpenAPI

Also known as: OpenAPI Specification, OAS

OpenAPI is a language-agnostic specification format for describing HTTP APIs. An OpenAPI document, written in JSON or YAML, lists an API’s endpoints, the parameters they accept and the responses they return. People and programs can then understand the API without reading its source code. “Open API” is also used for publicly available APIs in general. This entry covers the specification.

At a glance

Publisher
OpenAPI Initiative (Linux Foundation)
Connects
HTTP APIs with developers and tools through a machine-readable description
Status
specification of the OpenAPI Initiative, current version 3.2.1 (2026-09-10)
License
Apache 2.0
Specification
OpenAPI Specification

Last checked:

How is an OpenAPI document structured?

The specification defines a root OpenAPI object with several parts. The Info object holds metadata such as title and version. The Paths object lists endpoints and their operations. The Components object stores reusable schemas, parameters and responses. Server and security definitions complete the document. Entry files are conventionally named openapi.json or openapi.yaml.

The specification is maintained by the OpenAPI Initiative under the Linux Foundation. It grew out of the Swagger specification, which SmartBear donated. The latest version listed at spec.openapis.org is 3.2.1, released in September 2026.

What is OpenAPI used for?

The OpenAPI Initiative lists use cases such as API design, generating client and server code, documentation, API gateway configuration, and contract and security testing. Because the format is machine-readable, tools can process the description directly.

For discovery, RFC 9727 defines the path /.well-known/api-catalog, where a site can publish a machine-readable list of its APIs. Cloudflare checks for this catalog in its Agent Readiness Score.

Example

The example uses version 3.1.0 for illustration.

YAML
openapi: 3.1.0
info:
  title: Example API
  version: "1.0"
paths:
  /pages/{id}:
    get:
      summary: Get a page
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The page was found.

Common mistakes

  • Omitting the openapi field. It is required and must hold the version number of the specification the document uses.
  • Naming the entry file arbitrarily. The specification recommends openapi.json or openapi.yaml, so tools and people can find it.
  • Using a YAML parser of a different version. The specification recommends YAML 1.2 so that JSON and YAML convert into each other without loss.

FAQ

What is the difference between OpenAPI and Swagger? Swagger was the original name of the specification. After the donation to the OpenAPI Initiative it became the OpenAPI Specification.

Is OpenAPI the same as REST API? No. A REST API is an API style. OpenAPI is a format to describe HTTP APIs, including REST ones.

Sources

  1. What is OpenAPI? – OpenAPI Initiativeopenapis.org
  2. OpenAPI Specification v3.2.1 – spec.openapis.orgspec.openapis.org
  3. About the OpenAPI Initiativeopenapis.org
  4. RFC 9727: api-catalog – IETFrfc-editor.org

Last updated: