What is OpenAPI?

OpenAPI, formerly known as Swagger, is an interoperable, machine-readable, and human-friendly specification format that is used to define HTTP APIs. It relies on JSON Schema to describe the API’s underlying data. OpenAPI documents can be created with a code editor or an API design tool in the early phases of the API lifecycle, or they can be generated from existing API code, live traffic, or logs.

OpenAPI documents serve many purposes. First and foremost, they establish an API contract between the API’s consumers and producers, and they can be used to generate documentation, mock servers, client SDKs, and API tests. An OpenAPI document can also act as a guide for server and client implementation, and it can be used to perform API governance checks, as well.

Here, we’ll explore the history of OpenAPI, clarify the relationship between OpenAPI and Swagger, explore how an OpenAPI document is structured, and discuss the main benefits and limitations of OpenAPI. Let’s dive in.

What is the history of OpenAPI?

OpenAPI has a long history that can be divided into the following evolutionary phases:

Phase 1: The specification is born

In 2011, the team that was working on the Wordnik online dictionary created the first generation of Swagger tools to help generate documentation and an SDK for their API. All of these tools were powered by a JSON document that used the Swagger 1.0 Specification to describe the API, but the specification itself was not visible or important to most users at the time. They were most excited about SwaggerUI, as well as the code generation features.

Phase 2: The specification evolves

The release of Swagger 2.0, which occurred in 2014, included the Swagger Editor, as well as support for both JSON and YAML specification documents. This release brought the specification itself into the spotlight and led to a significant increase in adoption as more people began to use it in a design-first approach.

Phase 3: The specification gets a new home

The Swagger 2.0 Specification was acquired by SmartBear Software in 2015, who donated it to the OpenAPI Initiative (under the Linux Foundation) later that year. It was renamed “the OpenAPI Specification,” but the Swagger tools kept their name and remained the property of SmartBear.

Phase 4: The specification is improved

The OpenAPI Specification is now managed by a Technical Steering Committee (TSC) that works to develop the specification in an open, transparent way. OpenAPI 3.0 was released in July 2017, and OpenAPI 3.1 was released in February 2021. OpenAPI 3 has several improvements over Swagger 2.0, including support for OpenID Connect, the ability to define multiple servers, and more flexibility when serializing arrays and objects in query parameters.

Is OpenAPI the same as Swagger?

This is a complicated question, and the answer is, “yes and no.” OpenAPI and Swagger are the same thing in the sense that the OpenAPI 3 Specification is the newer version of the Swagger 2 Specification. However, “Swagger” itself is a suite of open source and proprietary tools that leverage the OpenAPI Specification.

How does the OpenAPI Specification work?

The OpenAPI Specification works by describing HTTP APIs in an established format that is easy for machines and humans to read. An OpenAPI document typically includes:

• General information about the API, such as its name and version, where the API is hosted, a human-readable description of its features, and a way to get in touch with the API’s producer.
• Descriptions of the API’s operations, callbacks, and webhooks, as well as their parameters and responses. This should include their data models and any necessary human-readable details.
• Information about the API’s security modes—such as Basic Authentication, OAuth 2.0, or Mutual TLS—as well as how each operation is secured (i.e., which OAuth scopes are used).
• A list of reusable components—such as schemas, parameters, and responses—that can be shared across operations within the OpenAPI document, as well as across other OpenAPI documents. For instance, an Error data model or a “400 Bad Request” response can be defined once and reused in many operations.
• Examples of parameters, responses, and any other pieces of data.

Let’s look at each of these components in a little more detail by exploring the structure of an OpenAPI document.

The structure of an OpenAPI document

An OpenAPI document can be written in JSON or YAML, and it will have the following structure:

# The Version of the OpenAPI Specification used (swagger for version 2)
openapi: "3.1.0"

# General information about the API
info: ...

# Paths and operations
paths:
  /books:
    get: ...

# Reusable components
components: ...

General information
The info section of the document will typically include the API’s title, version, and description. It may also include contact information for the API’s producer.

# General information about the API
info:
  title: Library
  version: "1.0"
  description: |
    The Library API provides _everything_
    you need to manage books.
  contact:
    url: https://api.library.com/contact

Paths and operations
The paths section of the document will include the paths and operations through which the API’s resources can be accessed. For instance, the following snippet describes a GET /books operation with an optional title parameter (GET /books?title=value) that will return JSON data.

# Paths
paths:
  /books:

# An operation (GET /books)
get:
  summary: Search for books
  parameters:
    - name: title
      in: query
      # A JSON Schema
      schema:
        type: string
   responses:
    200:
      description: Found books
      content:
        application/json:
          schema: ...

In the snippet above, you can see that the title query parameter is defined as a simple string. This is an example of how every piece of data in an OpenAPI document—such as query parameters, headers, and request and response bodies—is defined with JSON Schema.

Components
JSON Schema also supports more complex data models. The 200 response in the snippet below returns an array of objects. The schema of each object (or item) is defined with a reference ($ref) to a reusable component, which is located under the components.schemas section of the OpenAPI document. In this case, the response will include an array of book objects.

# Paths
paths:
  /books:
    get:
      ...
      responses:
        '200':
          description: Found books
          content:
            application/json:
              # A JSON Schema
              schema:
               type: array
               items:
                 # A reference to a reusable schema
                 $ref: '#components/schemas/Book'

components:
  schemas:
    # A reusable schema named Book
    Book:
      properties:
        isbn:
          type: string
        title:
          type: string
        author:
          type: string
        price:
          type: number

What are the benefits of OpenAPI?

OpenAPI offers many benefits that make it one of the most popular API specifications today. These benefits include:

• Many paths to creation: OpenAPI documents can be authored by hand, or they can be automatically generated from code, live traffic, or with design tools.
• Interoperability: OpenAPI is an interoperable industry standard. It provides a bridge between API vendors, portals, gateways, and open source tools, and it can be used to generate API server code, client code, code annotations, and SDKs.
• Easier collaboration: OpenAPI facilitates collaboration among everyone who is involved in creating and consuming APIs, such as business stakeholders, product owners, designers, developers, technical writers, and consumers. It can be used by these stakeholders across the entire API lifecycle.
• A universal language for describing APIs: OpenAPI documents clearly describe what an API—or group of APIs—does. This is especially useful if you are trying to understand an API you didn’t create yourself, or if you are trying to wrap your head around the API surface of a system, organization, or domain that spans many organizations.
• A guide for governance: The OpenAPI Specification acts as a useful guide for creating industry-standard API governance rules.

What are the limitations of OpenAPI?

Every technology comes with its own set of tradeoffs, and OpenAPI is no different. Some of the limitations of OpenAPI are:

• Complex maintenance: Large OpenAPI documents can be difficult to maintain without dedicated tools.
• Repetition: It can be hard to avoid repeating yourself when authoring an OpenAPI document. For example, you may need to define the same 401 and 500 errors on all operations, or the same pagination parameters on all search operations. Still, a special interest group is working on an overlay specification to solve this problem, and projects such as Microsoft TypeSpec can help, as well.
• Lack of workflow support: It’s currently not possible to define sequences of API calls with OpenAPI alone. However, Postman Collections supports this use case, and an OpenAPI Special Interest Group (SIG) is working on a workflow specification.
• Confusion with Swagger: The name change created confusion, and many people remain unaware of OpenAPI 3. The slow adoption rate has also contributed to the slow pace of tooling updates.
• Limited tooling: OpenAPI 3.1 is still very new, which means that tooling support is limited (but growing).
• Incompatibility with other API architectures: The OpenAPI Specification is an excellent choice for REST/HTTP APIs, but it is not suitable for RPC or SOAP APIs. And for asynchronous APIs—especially those that are not HTTP-based—it’s best to use the AsyncAPI Specification.