OpenAPI 3.1 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.1 specification, from the basics of document structure to advanced topics like security, webhooks, and overlays. A 3.2 version of this guide is also available.

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 and 3.1 with its full JSON Schema alignment.
• 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 main sections of an OpenAPI document: version, info, servers, paths, components, security, webhooks, and tags.
• API servers: defining base URLs for different environments with server variables.
• Paths and operations: describing endpoints and HTTP methods with request bodies and responses.
• Parameters: path, query, header, and cookie parameters with types and validation.
• Parameter serialization: how arrays and objects are encoded in URLs using styles like form, spaceDelimited, and deepObject.
• HTTP requests: defining request bodies with content types and schemas.
• HTTP responses: documenting status codes, response headers, and content types.
• Components: reusable schemas, parameters, responses, and security schemes referenced with $ref.

Defining data models #

• Schemas and data types: types, formats, validation keywords (enum, minimum, maximum, pattern), and readOnly/writeOnly.
• JSON Schema in OpenAPI: the relationship between OpenAPI 3.1 and JSON Schema Draft 2020-12.
• Examples and defaults: providing sample values at schema, media type, and parameter levels.
• Schema composition: combining schemas with allOf, anyOf, and oneOf for polymorphism and inheritance.
• Representing XML: customizing XML element names, attributes, and namespaces.

Advanced topics #

• Multiple content types: serving JSON, XML, CSV, and other formats from a single endpoint.
• Multipart form data: describing form submissions that combine text fields and files.
• File uploads: direct binary uploads and multipart uploads with encoding.
• Error formats: standardized error responses with RFC 9457 Problem Details and JSON:API.
• Security: authentication schemes (API keys, HTTP bearer, OAuth2, OpenID Connect, mutual TLS) with scopes.
• Callbacks and webhooks: describing asynchronous events sent by the API to clients.
• Splitting documents with $ref: managing large API definitions across multiple files for better collaboration.

Documenting APIs #

• Descriptions and summaries: writing clear summaries and descriptions that improve developer experience.
• Grouping with tags: organizing endpoints into logical sections with descriptions and ordering.
• External documentation: linking to tutorials and guides from operations, tags, and schemas.

Extending OpenAPI #

• Specification extensions: adding custom x-* properties for vendor-specific features.
• Overlays: non-destructively modifying OpenAPI documents using JSONPath targeting.

Workflow and best practices #

• The perfect modern OpenAPI workflow: using OpenAPI as a single source of truth with automated linting, testing, documentation, and SDK generation.

Quick reference #

• The Cheat Sheet: a downloadable one-page visual reference of the specification.