OpenAPI Specification

What it is

The OpenAPI Specification (OAS) defines a standard, language-agnostic format for describing HTTP APIs. An OpenAPI document, written in YAML or JSON, lists an API's paths, operations, parameters, request bodies, responses, schemas and security schemes. Tools read that document to render API reference pages, generate client SDKs and server stubs, run contract tests and power interactive "try it" consoles.

The specification is maintained by the OpenAPI Initiative, a Linux Foundation project. The page at spec.openapis.org/oas/latest.html always shows the latest published version; as of 2026-09 that was version 3.2.1, dated 10 September 2026. Many real-world APIs still use 3.0 or 3.1 descriptions, so expect to see all of them.

Why it matters for non-coding roles

API reference is a core part of developer documentation. In many teams the reference is generated from an OpenAPI file, and the technical writer's job is to improve the descriptions, summaries, examples and error explanations inside that file rather than write reference pages by hand. Developer advocates use OpenAPI files to build sample requests and demos, and product managers who own API products review them to understand what is being promised to customers.

How to approach it

The specification is precise and dense. Do not read it front to back as a beginner. Instead:

1. Start with the Learn OpenAPI guide from the same organisation.
2. Open a real OpenAPI file from a public API and match each part to the spec's sections: info, servers, paths, components, security.
3. Use the spec as a reference when you meet something unfamiliar, such as oneOf in a schema or a links object.
4. Practise by writing a small OpenAPI description for a toy API and rendering it with a free tool such as Swagger UI or Redoc.

Prerequisites

Understand HTTP methods, status codes and JSON first. Basic YAML syntax helps.

Free vs paid

Free. The specification is open and licensed under Apache 2.0 on GitHub.

Common questions

Is OpenAPI the same as Swagger? Swagger was the original name of the specification before it moved to the OpenAPI Initiative. Swagger now refers to a set of tools from SmartBear that work with OpenAPI.

Does it cover GraphQL or gRPC? No. Those have their own schemas and documentation tools.