OpenAPI Specification

A standard, language-neutral way to describe an HTTP API in one JSON or YAML document, from which tools generate docs, client SDKs, server stubs, tests, gateway configs and AI tools.

OpenAPI Initiative project

What it is: Web APIs
Type: Open source
Made by: OpenAPI Initiative (Linux Foundation), started as Swagger at Wordnik
Foundation: OpenAPI Initiative, joined November 2015. SmartBear donated the Swagger Specification when the OpenAPI Initiative was announced. Part of the Linux Foundation
License: Apache 2.0
Facts checked: 28 October 2026

What it is

An OpenAPI description is a JSON or YAML document that lists an API’s paths, the HTTP operations on each (get, post and so on), their parameters, request bodies and possible responses, and the security schemes that protect them. Shared data models live under components, written as Schema Objects. Since version 3.1 a Schema Object is JSON Schema: by default the 2020-12 draft with a few OpenAPI keywords added, so the same schemas can validate payloads elsewhere. The specification calls itself “a standard, programming language-agnostic interface description for HTTP APIs”: it says what an API accepts and returns, not how it is built or what the calls mean together.

Its value is the tooling that reads one file. Swagger UI and Redocly render reference docs; OpenAPI Generator and Microsoft’s Kiota generate client SDKs and server stubs; Spectral and Redocly CLI lint a description against a style guide; AWS API Gateway, Google API Gateway and Azure API Management import one to set up routes; and Speakeasy turns one into SDKs or an MCP server whose tools are the API’s operations. Teams either write the description first and generate code from it, or generate it from code, as FastAPI does from Python type hints. The OpenAPI Initiative also publishes two companion specifications: Arazzo, for multi-step workflows across API calls, and Overlay, for patching a description without editing its source.

Why teams pick it

One machine-readable contract drives docs, SDKs, mocks, tests, linting and gateway setup, so they stay consistent with each other
Works with any HTTP API style and any server language: it describes the HTTP surface, not the implementation
Vendor-neutral and widely supported: the three big clouds’ API gateways import it, and the main SDK, docs and linting tools read it
Schemas are JSON Schema since 3.1, so the same models can validate requests and data outside the API
Open process: anyone can join the weekly calls and propose changes, and the 3.x line has kept changes small and documented

Watch out for

Tool support trails the specification: AWS API Gateway imports only OpenAPI 2.0 and 3.0, though 3.1 came out in 2021 and 3.2 in 2025, so check every tool in your chain before using newer features
It describes single HTTP operations, not how they fit together; call sequences need Arazzo or prose, and event-driven APIs are usually described with AsyncAPI instead
A description written by hand drifts from the code unless CI checks one against the other; one generated from code is only as good as the annotations
Flexible schemas (oneOf, anyOf, discriminators) are valid OpenAPI but hard for code generators to turn into clean types, so generated SDKs vary a lot in quality

Alternatives

What all web apis have in common →Compare side by side →

GraphQLOpen sourceA query language and runtime for APIs: the server publishes a typed schema, and each client asks one endpoint for exactly the fields it needs.

Protocol BuffersOpen sourceGoogle’s schema-first binary encoding: messages defined in .proto files, fields identified by number, code generated for each language.

gRPCOpen sourceGoogle’s open RPC framework: describe a service in a .proto file, generate typed clients and servers, and call them over HTTP/2 with streaming, deadlines and standard status codes.

AsyncAPIOpen sourceA specification, and a set of open-source tools, for describing event-driven APIs in one YAML or JSON document: the brokers an application connects to, the channels it sends to or receives from, and the messages on them.

Hasura DDNCommercialHasura Data Delivery Network: you describe models, commands, relationships and permissions as metadata, and a Rust engine serves them as one GraphQL (or JSON:API) API over databases and code reached through data connectors.RESTOpen sourceThe architectural style behind most HTTP APIs: resources with URLs, a few standard methods, status codes and cacheable responses, named by Roy Fielding in 2000.

How it fits with other technologies

What OpenAPI Specification uses

An OpenAPI 3.2 description of one operation · yaml

openapi: 3.2.0
info:
  title: Orders API
  version: 1.4.0
servers:
  - url: https://api.example.com/v1
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      tags: [orders]
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '404':
          description: No such order
      security:
        - bearer: []
components:
  securitySchemes:
    bearer: { type: http, scheme: bearer }
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id: { type: string }
        status: { enum: [pending, paid, cancelled] }
        total_cents: { type: integer, minimum: 0 }

What each version changed#

Each minor version can break documents written for the one before, so tools state which versions they read. Patch releases such as 3.1.2 and 3.2.1 only clarify the text.

	Released	Main changes
Swagger 2.0	September 2014	The last version under the Swagger name; still read by most tools, and the newest that some gateways accept
OpenAPI 3.0	July 2017	First release under the OpenAPI name: reusable `components`, request bodies, several servers per API, links and callbacks
OpenAPI 3.1	February 2021	Schema Objects become JSON Schema 2020-12, with breaking changes to file uploads; webhooks; a `jsonSchemaDialect` field
OpenAPI 3.2	September 2025	Nested tags; the `QUERY` method and any other method; streaming media types such as server-sent events; a `querystring` parameter location

OpenAPI 3.2.1, a patch release that clarifies parameter encoding, came out on September 10, 2026.
Work on a 4.0, called Moonwalk, has no planned end date; its group recommends the 3.x versions in the meantime.

The OpenAPI Initiative’s other specifications#

Two companion formats sit next to OpenAPI and point into OpenAPI descriptions rather than replacing them.

Arazzo

1.0 in 2024, 1.1 in 2026

Describes sequences of API calls and the dependencies between them, such as “log in, then create an order, then pay”, in a form both people and machines can follow; its README lists generated docs, test automation and deterministic calls by AI models among the uses.

Overlay

1.0 in 2024, 1.2 in 2026

A separate document of changes to apply to an OpenAPI description, such as translated text, per-environment settings or gateway metadata, so the source description stays untouched.

Moonwalk

4.0 in progress

A special interest group designing the next major version, which aims to describe any HTTP API, separate concerns into modules and come with an automatic upgrade from 3.x.

See it in a real stack

No architecture uses OpenAPI Specification yet. Drop it into the playground and wire it up yourself.Open playground →

Where it came from2011–2025

Tony Tam started Swagger in early 2010 at Wordnik, an online dictionary company, as a way to describe its API. The first Swagger Specification was released in August 2011, together with Swagger UI and a code generator, and version 2.0 followed in September 2014.

In March 2015 SmartBear Software bought the Swagger project from Reverb Technologies, Wordnik’s parent company. Eight months later, on November 5, 2015, the Linux Foundation announced the Open API Initiative with 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, Restlet and SmartBear, and SmartBear donated the specification to it. On January 1, 2016 it was renamed the OpenAPI Specification; “Swagger” stayed with SmartBear’s tools.

The first version made under the new governance, 3.0, came out in July 2017. Version 3.1 in February 2021 replaced OpenAPI’s own variant of JSON Schema with the real thing, and 3.2 in September 2025 added streaming and new HTTP methods. Since 2024 the initiative has also published Arazzo and Overlay.

Why it’s built this way

Give the specification to a neutral foundation: Competing API vendors were unlikely to build on a format one of them owned. At the launch, Apigee called open governance under the Linux Foundation “the necessary next step”, and Restlet said the API community should “unite around a common API language”.
Rename it, but let SmartBear keep “Swagger”: Renaming separated the vendor-neutral description format from SmartBear’s Swagger tools, which kept the old name.
Adopt JSON Schema in 3.1, even at the cost of breaking changes: Earlier versions used an extended subset of an old JSON Schema draft, so schemas didn’t behave the same in OpenAPI tools and JSON Schema validators. Version 3.1 moved to JSON Schema 2020-12 and accepted breaking changes to do it.

Timeline

2011
Swagger 1.0 released in August, after Tony Tam started it at Wordnik in 2010
2014
Swagger 2.0 released in September
2015
SmartBear buys Swagger in March; OpenAPI Initiative announced on November 5
2016
Renamed the OpenAPI Specification on January 1
2017
OpenAPI 3.0.0 released on July 26
2021
OpenAPI 3.1.0 released on February 16, built on JSON Schema 2020-12
2024
Arazzo 1.0 and Overlay 1.0 published
2025
OpenAPI 3.2.0 released on September 19

Sources21 · facts checked 28 October 2026

Improve this page on GitHub