More About Swagger Details

The (OAS) is a widely adopted, standardized format for describing REST APIs. You can use OpenAPI to detail every part of your API, including endpoints, operation parameters, request responses, and authentication flows. The OpenAPI format is easy for both developers and machines to read and understand. What’s harder to immediately decipher is how the versions differ.

At the time of publication, almost everyone will likely want to use OpenAPI v3.0, the latest official major version that was released in 2017.

Some folks are on OpenAPI 2.0 due to being stuck there with tooling that still has not added support for OpenAPI v3.0. Some people might talk about OpenAPI v3.1, but whilst it is still in the “Release Candidate” stage there is essentially no tooling support for it.

However, for those digging into the nuances between versions, it’s worth looking into the details.

There are currently two major OpenAPI releases, 2.0 and 3.0 (the latest release is 3.0.3). Version 3.1 was on June 18, 2020, as an initial release candidate. While it takes some important steps forward, it adds to the confusion over which version to use. In this post, we’ll look at some of the key differences between OpenAPI 2.0, 3.0, and 3.1.

Differences Between OpenAPI 2.0 and 3.0 The two major versions of OpenAPI have the most significant differences, which come from their history. OpenAPI 2.0 was previously known as Swagger and is intended to replace it with backward compatibility. Once adopted as an open format, the community began working on OpenAPI 3.0, released in 2017. Let’s highlight some of the significant changes made to OpenAPI components in version 3.0.