# OpenAPI vs. Swagger

Swagger 2 and [OpenAPI](https://blog.postman.com/what-is-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](https://www.postman.com/api-platform/api-design/), [API governance](https://www.postman.com/api-platform/api-governance/), [API documentation](https://www.postman.com/api-platform/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](https://blog.postman.com/what-is-json/) and [YAML](https://blog.postman.com/what-is-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](https://blog.postman.com/what-is-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](https://www.postman.com/api-platform/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`: ![](https://blog.postman.com/wp-content/uploads/2023/08/OpenAPI-vs-Swagger-01-1000x613.png)### 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. ![](https://blog.postman.com/wp-content/uploads/2023/08/OpenAPI-vs-Swagger-02-r2.png)OpenAPI 3 users can define every piece of data with JSON Schema.### 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: ![](https://blog.postman.com/wp-content/uploads/2023/08/OpenAPI-vs-Swagger-03-1000x471.png)### 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. ![](https://blog.postman.com/wp-content/uploads/2023/08/OpenAPI-vs-Swagger-04-1-1000x354.png)Objects and arrays can both be serialized in OpenAPI 3.### 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: ![](https://blog.postman.com/wp-content/uploads/2023/08/OpenAPI-vs-Swagger-05-1000x493.png)OpenAPI 3 allows you to define asynchronous communication patterns in your OpenAPI document.### 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: ![](https://blog.postman.com/wp-content/uploads/2023/08/OpenAPI-vs-Swagger-06-1000x430.png)OpenAPI 3 allows you to define multiple servers. 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: ![](https://blog.postman.com/wp-content/uploads/2023/08/OpenAPI-vs-Swagger-07-1000x457.png)Servers can be defined with variables.### Improved security modes

 OpenAPI 3.0 removed Basic Auth, fixed [OAuth 2.0](https://blog.postman.com/what-is-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: ![](https://blog.postman.com/wp-content/uploads/2023/08/OpenAPI-vs-Swagger-08-1000x479.png)### 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. ![](https://blog.postman.com/wp-content/uploads/2023/08/OpenAPI-vs-Swagger-09-1000x515.png)OpenAPI 3.0 supports multiple documented examples on request and response bodies, as well as on query parameters and headers.### 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. ![](https://blog.postman.com/wp-content/uploads/2023/08/OpenAPI-vs-Swagger-10-1000x481.png)OpenAPI has expanded support for summaries and descriptions.