OpenAPI Tips

Everything You Need to Know About OpenAPI

Nolan Di Mare Sullivan

May 17, 2024

Speakeasy has released a comprehensive, Open Source reference to writing OpenAPI specifications.

The reference has AI-search built in to help you quickly answer any questions that you may have.

If you are interested in contributing, the GitHub repo can be found here (opens in a new tab).

Why is OpenAPI Important?

Consistent API design is essential. Building 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 create and maintain all your surfaces manually will inevitably lead to frustration and inconsistencies. With OpenAPI, you get much greater visibility into your API, and you can unify all aspects of your errors, responses, and parameters, ensuring consistency.

If you are building a RESTful API, OpenAPI should be the source of truth that automates the creation of all your public surfaces (docs, SDKs, etc.)

This documentation will help you understand the OpenAPI Specification.

What is OpenAPI?

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.

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: 3.1.0
info:
  title: The Speakeasy Bar
  version: 1.0.0
servers:
  - url: https://speakeasy.bar
    description: The production server
security:
  - apiKey: []
tags:
  - name: drinks
    description: Operations related to drinks
paths:
  /drinks:
    get:
      tags:
        - drinks
      operationId: listDrinks
      summary: Get a list of drinks
      responses:
        "200":
          description: A list of drinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
components:
  schemas:
    Drink:
      type: object
      title: Drink
      properties:
        name:
          type: string
        price:
          type: number
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header

To break that down piece by piece:

openapi: The version of the OpenAPI Specification that the document conforms to, should be one of the supported versions.

openapi: 3.1.0

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.

info:
  title: The Speakeasy Bar
  version: 1.0.0

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.

servers:
  - url: https://speakeasy.bar
    description: The production server

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.

security:
  - apiKey: []

tags: Contains an optional list of tags that are generally used to group or categorize a set of Operations.

tags:
  - name: drinks
    description: Operations related to drinks
paths:
  /drinks:
    get:
      tags:
        - drinks
      operationId: listDrinks
      summary: Get a list of drinks

paths: Contains the paths and operations available within the API.

paths:
  /drinks:
    get:
      tags:
        - drinks
      operationId: listDrinks
      summary: Get a list of drinks
      responses:
        "200":
          description: A list of drinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"

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.

components:
  schemas:
    Drink:
      type: object
      title: Drink
      properties:
        name:
          type: string
        price:
          type: number
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header

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 $ref keyword to reference the components file from the main file. Click here for more information on references.
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.

How is this different from the official OpenAPI documentation?

The goal of this documentation is to provide a practitioner’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?

There are several versions of the OpenAPI specification in circulation: 2.0 (also known as Swagger), 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, which gives you access to a much larger ecosystem of tools and libraries.

Speakeasy’s documentation covers versions 3.0.x and 3.1.x of the OpenAPI specification. Where there is an important difference between the two versions, we call it out specifically, otherwise, the documentation will apply to both versions.