OpenAPI 3.2 Specification Complete Guide
OpenAPI is the industry standard for describing HTTP APIs. Maintained by the OpenAPI Initiative under the Linux Foundation, it provides a structured, machine-readable format that tools can use to generate documentation, client libraries, tests, mock servers, and more.
This guide covers every aspect of the OpenAPI 3.2 specification, from the basics of document structure to advanced topics like streaming, pagination, and overlays.
Introduction #
- What is OpenAPI?: what the specification is, what an OpenAPI document looks like, and the key concepts (documents, operations, schemas, security).
- History and evolution: from Swagger to OpenAPI 3.0, 3.1 (JSON Schema alignment), and 3.2 (streaming, pagination, tag hierarchies).
- Benefits of using OpenAPI: how OpenAPI accelerates documentation, testing, SDK generation, onboarding, and collaboration across teams.
Understanding OpenAPI structure #
The core building blocks of every OpenAPI document.
- Basic structure: the eight main sections of an OpenAPI document: version, info, servers, paths, components, security, webhooks, and tags.
- API servers: defining base URLs for different environments (dev, staging, production) with support for server variables and dynamic substitution.
- Paths and operations: describing endpoints and HTTP methods (GET, POST, PUT, DELETE, and the new QUERY method in v3.2) with request bodies and responses.
- Parameters: path, query, header, and cookie parameters with types, validation, and reusability via components.
- Parameter serialization: how arrays and objects are encoded in URLs using styles like form, spaceDelimited, pipeDelimited, and deepObject.
- HTTP requests: defining request bodies with content types, schemas, and required/optional flags.
- HTTP responses: documenting status codes, response headers, content types, and empty responses.
- Components: reusable schemas, parameters, responses, request bodies, headers, examples, and security schemes referenced with
$ref.
Defining data models #
- Schemas and data types: types (string, number, integer, boolean, array, object, null), formats (date-time, email, uuid), validation keywords (enum, minimum, maximum, pattern), and readOnly/writeOnly.
- JSON Schema in OpenAPI: the relationship between OpenAPI and JSON Schema Draft 2020-12, and the four additional OpenAPI-specific keywords.
- Examples and defaults: providing sample values at schema, media type, and parameter levels for documentation and mock servers.
- Schema composition: combining schemas with allOf (AND), anyOf (OR), and oneOf (XOR) for polymorphism and inheritance.
- Representing XML: customizing XML element names, attributes, namespaces, and array wrapping with the xml keyword.
Advanced topics #
- Splitting documents with $ref: managing large API definitions across multiple files and URLs for better collaboration and reusability.
- Multipart form data: describing form submissions that combine text fields, files, and metadata in a single request.
- Pagination: query parameters, response metadata, link-based, header-based, and cursor pagination strategies.
- File uploads: direct binary uploads and multipart uploads with base64 encoding and content type negotiation.
- Multiple content types: serving JSON, XML, CSV, and other formats from a single endpoint.
- Error formats: standardized error responses with RFC 9457 Problem Details, JSON:API errors, and reusable error schemas.
- Security: authentication schemes (API keys, HTTP bearer, OAuth2, OpenID Connect, mutual TLS) applied globally or per-operation with scopes.
- Callbacks and webhooks: describing asynchronous events sent by the API to clients, including operation callbacks and standalone webhooks.
- JSON streaming: describing streamed responses (JSONL, NDJSON, Server-Sent Events) with the new itemSchema keyword in v3.2.
Documenting APIs #
- Descriptions and summaries: writing clear summaries and descriptions for operations, parameters, tags, and responses that improve developer experience.
- Grouping with tags: organizing endpoints into logical sections with descriptions, ordering, and the new tag hierarchies in v3.2.
- External documentation: linking to tutorials, guides, and knowledge bases from operations, tags, and schemas.
Extending OpenAPI #
- Specification extensions: adding custom x-* properties for vendor-specific features (code samples, beta flags, feedback links) without breaking compatibility.
- Overlays: non-destructively modifying OpenAPI documents using JSONPath targeting to add descriptions, hide internal endpoints, or customize for different audiences.
Workflow and best practices #
- The perfect modern OpenAPI workflow: using OpenAPI as a single source of truth in Git, with automated linting, contract testing, documentation deployment, mock servers, and SDK generation.
Quick reference #
- The Cheat Sheet: a downloadable one-page visual reference of the entire specification for quick lookup.