OpenAPI vs. Swagger

Swagger 2 and OpenAPI 3 are API specifications that describe RESTful HTTP APIs in YAML- or JSON-based documents that can be read by both machines and humans. They are not competing formats; instead, OpenAPI 3.0 and 3.1 are the newer versions of Swagger 2.0. They share the same purpose and support the same use cases, such as API design, API governance, API documentation, server and client code generation, and API gateway configuration. However, OpenAPI 3 brings many enhancements to Swagger 2 that facilitate the creation of consistent API descriptions that are more accurate representations of the APIs themselves.

The history of OpenAPI and Swagger

In 2011, the Wordnik dictionary team created the Swagger Specification as part of the Swagger toolkit, which included Swagger UI, Swagger Codegen, and an annotations library. These tools, which were intended to facilitate API documentation and SDK generation, received much more attention than the specification itself.

Version 2 of the Swagger toolkit was released in 2014, along with the Swagger 2.0 Specification. Version 2 included the Swagger Editor, which supported editing of Swagger 2.0 documents in both JSON and YAML. It was at this point that the Swagger 2.0 Specification became very popular for RESTful API design, as API developers began leveraging it to produce a formal description of their API before the development process began.

In 2015, the Swagger 2.0 Specification was donated to the newly created OpenAPI Initiative, which operates under the Linux Foundation. Members of the OpenAPI Initiative include SmartBear, 3scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, Postman, SAP, and Salesforce, and they share the goal of promoting a vendor neutral and open source API description format.

A new version of the specification was released in 2017 under the name “OpenAPI Specification 3.0.” OpenAPI 3.1 was released in 2021, and discussions about OpenAPI 4 started at the end of 2022. There are other specifications that aim to describe RESTful HTTP APIs, but OpenAPI is the industry standard today.

Similarities between OpenAPI and Swagger

Many people are confused by the distinction between OpenAPI and Swagger, but Swagger 2 is simply an earlier version of OpenAPI 3. OpenAPI 3 brought many welcome additions, but the two versions still have a lot in common. For instance:

• Both specifications support JSON and YAML formats.
• Both specifications rely on JSON Schema to describe the API’s underlying data (but they use different versions of JSON Schema, which we’ll discuss soon).
• The info block in both specifications provides the same information about the API, such as its name, description, and point of contact. However, OpenAPI 3.1 added a few new properties, such as summary and license.identifier, which contains an SPDX license expression for the API.
• Both specifications share the overall organization of paths and HTTP methods, but OpenAPI 3 supports descriptions of all data with JSON Schema and relevant media types.
• Both specifications support complex workflows across the entire API lifecycle, including API design, documentation, testing, code generation, and tool configuration.

Differences between OpenAPI and Swagger

OpenAPI 3.0 and 3.1 include many improvements to Swagger 2, such as:

Centralized reusable components

With Swagger 2.0, users must define reusable components under the definitions, parameters, responses, and securityDefinitions fields. OpenAPI 3 has moved these categories to the components block in order to avoid confusion with elements such as security, which defines behavior that applies across all operations (note that definitions is now called schemas and securityDefinitions is now called securitySchemes).

OpenAPI has introduced new reusable components, as well. OpenAPI 3.0 brought reusable examples and headers, and OpenAPI 3.1 brought reusable pathItems:

Expanded support for JSON Schema

In Swagger 2.0, non-body parameters and response headers do not leverage a real JSON Schema in the way that request and response bodies do. OpenAPI 3 brought much-needed consistency to data definition by allowing users to define every piece of data with JSON Schema. This also means that any piece of data can benefit from shared data models (which are located under components.schemas).

It’s important to note that different versions of OpenAPI use different versions of JSON Schema. OpenAPI 3.0 uses JSON Schema Draft 5 and includes support for oneOf, anyOf, and not, which make it easier to describe complex data structures and request/response payloads. OpenAPI 3.1 uses JSON Schema Draft 2020-12 by default, but it also allows users to use different versions by setting the jsonSchemaDialect property at the root level.

One data model per media type

Swagger allows users to indicate multiple media types for request and response bodies with the produces and consumes properties, but there can only be one schema for request and response bodies. In OpenAPI 3, you can define one schema per media type:

Enhanced parameter and header serialization

In Swagger 2.0, arrays can be serialized in query parameters or headers, but in OpenAPI 3.0, objects and arrays can both be serialized. This enhancement brings greater expressiveness and flexibility to define complex data structures, improves type validation, increases consistency in data modeling, and simplifies the documentation process.

Callbacks and webhooks

OpenAPI 3 allows you to define asynchronous communication patterns in your OpenAPI document, in which API operations are defined and called by the API provider but implemented by the API consumer. For instance, callbacks (introduced with OpenAPI 3.0) might be defined at the operation level, which will be called by the provider at the end of a long operation. Additionally, webhooks (introduced with OpenAPI 3.1) can be called by the provider in response to a specific event that occurs independently from a prior consumer call:

Multiple servers with variables

Swagger 2.0 allows an API to be hosted in a single place, which is defined with the schemes, host, and basePath properties. OpenAPI 3, however, allows you to define multiple servers. This enhancement can be useful if you want to run your API on both a mock server and a real API server:

A server can be defined with variables. The example below shows the same server configuration in OpenAPI 3.1—one with variables and one without:

Improved security modes

OpenAPI 3.0 removed Basic Auth, fixed OAuth 2.0 support, and added support for bearer tokens and OpenID Connect. OpenAPI 3.1 also introduced mutual TLS. As we mentioned above, security modes are now defined under components.securitySchemes, which helps avoid confusion with the universal security field:

Multiple documented examples

Swagger 2.0 only supports a single, undocumented example on request and response bodies. In contrast, OpenAPI 3.0 supports multiple documented examples on request and response bodies, as well as on query parameters and headers. Examples can also be defined under components.examples and reused across elements. This enhancement is useful for creating complete documentation, as well as mock servers.

More summaries and descriptions

OpenAPI 3.0 introduced the summary and description properties at the paths.* level, and OpenAPI 3.1 added a summary property at the info level, as well. These properties expand significantly on Swagger 2.0, which only includes a description property on the info level. The summary property enables users to add a short, one-line overview of the API, while the description property can be used to provide a more detailed description of an API element. Including both properties on the API itself, as well as its paths and operations, provides useful context and allows for more detailed documentation.