OpenAPI 3.1. Reference
Contribute!
Hi! 👋 This documentation is Open source. If you have any feedback, suggestions, or want to contribute, check out our GitHub repo (opens in a new tab).
Quicklinks
Introduction
API design is important. An API that developers enjoy interacting with turns a SaaS business into a platform. However great design is only useful if it's well-documented and consistently represented across every API surface area (docs, SDKs, etc.).
That is where OpenAPI comes in. Trying to manually create & maintain all your surfaces will inevitably lead to frustration and inconsistencies. Instead, if you are building a RESTful API, OpenAPI will be (should be) the source of truth that undergirds the creation of all your public surfaces (docs, SDKs, etc.).
This documentation will help you understand the OpenAPI Specification.
What is OpenAPI and why use it?
When we refer to OpenAPI, we mean the OpenAPI Specification - a standardized document structure for describing HTTP APIs in a way that humans and computers can understand.
OpenAPI files are written as JSON or YAML, describing your API using a standard vocabulary defined by the Specification - we'll call this JSON or YAML file an OpenAPI document.
A valid OpenAPI document describes your RESTful API and serves as the instruction set for tooling that generates API documentation, SDKs, and more. We will refer to an app or tool that reads an OpenAPI document to perform an action as an OpenAPI tool. Speakeasy is one such tool, a full list can be found here (opens in a new tab).
OpenAPI Document Basics
Your OpenAPI document is composed of keywords (some required, some optional). Together, the document covers the key elements of your API:
- What security is required to access it?
- Which endpoints expose which resources?
- How are those resources constructed?
openapi
The version of the OpenAPI Specification that the document conforms to, should be one of the supported versions (opens in a new tab).
Note: Speakeasy tooling currently only supports OpenAPI Specification versions 3.0.x and 3.1.x.
info
Contains information about the document including fields like title, version, and description that help to identify the purpose and owner of the document.
servers
Contains an optional list of servers the API is available on. If not provided, the default URL is assumed to be /, a path relative to where the OpenAPI document is hosted.
security
Contains an optional list of security requirements that apply to all operations in the API. If not provided, the default security requirements are assumed to be [], an empty array.
tags
Contains an optional list of tags that are generally used to group or categorize a set of Operations.
paths
Contains the paths and operations available within the API.
components
Contains an optional list of reusable schemas that can be referenced from other parts of the document. This improves the readability and maintainability of the document by allowing common schemas to be defined once and reused in multiple places.
openapi
The version of the OpenAPI Specification that the document conforms to, should be one of the supported versions (opens in a new tab).
Note: Speakeasy tooling currently only supports OpenAPI Specification versions 3.0.x and 3.1.x.
info
Contains information about the document including fields like title, version, and description that help to identify the purpose and owner of the document.
servers
Contains an optional list of servers the API is available on. If not provided, the default URL is assumed to be /, a path relative to where the OpenAPI document is hosted.
security
Contains an optional list of security requirements that apply to all operations in the API. If not provided, the default security requirements are assumed to be [], an empty array.
tags
Contains an optional list of tags that are generally used to group or categorize a set of Operations.
Format and File Structure
An OpenAPI document is a JSON or YAML file that contains either an entire API definition or a partial definition of an API and/or its components. All field names in the specification are case-sensitive unless otherwise specified.
A document can be split into multiple files, and the files can be in different formats. For example, you can have a JSON file that contains the API definition and a YAML file that contains the components, or a collection of files that contain partial definitions of the API and its components.
Generally, the main API definition file is called openapi.json or openapi.yaml, and the component files are called components.json or components.yaml, though this is not a requirement.
Some common organizational patterns for OpenAPI documents are:
- A single file that contains the entire API definition.
- A main file that contains the API definition and a components file that contains the components.
- This is normally achieved by using the
$refkeyword to reference the components file from the main file. Click here for more information on references.
- This is normally achieved by using the
- A collection of files that contain partial definitions of the API and its components.
- Some tools support this pattern by allowing multiple files to be provided. Others, such as the Speakeasy Generator, require the individual files to be merged into a single file before being passed to the tool, which can be achieved using the Speakeasy CLI tool. Click here for more information on the Speakeasy CLI merge tool (opens in a new tab).
How is this different to the official OpenAPI documentation?
The goal of this documentation is to provide a practioner's guide for developers interested in understanding the impact of OpenAPI design on their downstream API surfaces. This guide prioritizes approachability and practicality over technical completeness.
We've structured the documentation according to the needs of OpenAPI users of any skill level.
Which versions of the OpenAPI Specification does this documentation cover?
This documentation will cover versions 3.0.x and 3.1.x of the OpenAPI specification. Where there is an important difference between the two versions, we will call it out specifically, otherwise the documentation will apply to both versions.
OpenAPI is a standard for describing RESTful APIs. OpenAPI allows developers to define all the core elements of an API: endpoints, request and response data formats, authentication methods, etc.
There are several versions of the OpenAPI specification in circulation: 2.0 (also known as Swagger), 3.0, and 3.1.
Speakeasy supports OpenAPI versions 3.0 and 3.1. We recommend developers use OpenAPI version 3.1 for all projects. The advantage of using OpenAPI version 3.1 is that it is fully compatible with JSON Schema (opens in a new tab), which gives you access to a much larger ecosystem of tools and libraries.