OpenAPI does what Swagger don’t

Melinda Gutermuth

November 21, 2022

At this year’s API Specifications Conference (ASC), Postman ​​OpenAPI Technical Lead Arnaud Lauret (also known in the community as the API Handyman!) took the stage to share why, if you’re still using Swagger 2, it’s time to move to OpenAPI 3. Read on for key highlights of Arnaud’s presentation, and then check out the full video at the end of the post to learn even more.

A specification by any other name

Arnaud discussed how some developers view Swagger and OpenAPI, drawing on the Sega vs. Nintendo rivalry catchphrase from the 1990s, “Genesis does what Nintendon’t.” Because of their distinctly different names, it’s easy to mistake them for competing API specifications.

Let’s clear this up: it’s not Swagger vs. OpenAPI. Instead, it’s Swagger 2, then OpenAPI 3. The Swagger specification was donated to the OpenAPI Initiative in 2016, and it is now called the OpenAPI Specification (or OAS). This means that OpenAPI 3 is a newer version of the same API format. Both Swagger 2 and OpenAPI 3 are based on the same open source specification for designing RESTful web APIs.

Improvements all around

OpenAPI 3 includes notable enhancements compared to Swagger 2. Here are some of the things OpenAPI 3 does that Swagger 2 “don’t”:

• Better hosting definition: In OpenAPI 3, instead of defining a single fixed server, you can define multiple servers, describe them, and use variables.

• Better security definition: OpenAPI 3.0 fixes Oauth2 support, adds bearer tokens, and adds OpenID Connect support. OpenAPI 3.1 also introduces mutual TLS.

• Better data definition: OpenAPI 3 brings more flexibility when serializing arrays and objects in query parameters. OpenAPI 3.0 supports JSON Schema Draft 5, which offers more flexibility for data definition. Open API 3.1 supports the latest JSON Schema version (2020-12) and allows you to choose which version to use.

• Reverse API operations: OpenAPI 3.0 supports callbacks, and OpenAPI 3.1 adds support for webhooks as well.

• Multiple documented examples: OpenAPI 3 allows you to define multiple examples for request bodies, parameters, and responses. For each example, you can define a summary, description, and an external value.

Making the move to OpenAPI 3

You can move to OpenAPI 3 for free—almost. Upgrading to a new version always takes some work, and API specifications are no exception.

The following path represents a best-case scenario:

1. Make sure all of your tools, whether third-party or custom, are compatible with OpenAPI 3.
2. As needed, update your tools to a version that’s compatible with OpenAPI 3.
3. Convert your Swagger 2 documents to OpenAPI 3. There are many converters out there that can help you with this.

But we don’t live in an ideal world. Sometimes, upgrading tools doesn’t go smoothly. Arnaud talks about how he worked in an environment where some tools only worked with Swagger 2 and some tools only worked with OpenAPI 3. In this situation, he used the OpenAPI 3 specification as a source of truth. For any tools that didn’t support OpenAPI 3, he converted the documents back to Swagger 2 until the migration was complete.

How can we speed up adoption of new versions?

Developers often wait years before upgrading to the newest version of a tool or specification. This problem isn’t unique to APIs. Because API specifications are at the center of everything, the cost of change for everyone is extremely high. So, what can we do to make the process faster so that we can leverage new features sooner?

First of all, there is no adoption when no tools support the new version of the specification. At the same time, tools need their own support to keep working with new specification versions. To prevent everyone from reinventing the wheel, Arnaud thinks that specification creators should provide and support their own basic tools. He also believes that software vendors should be working together and investing in shared open source libraries that everyone, including themselves, can use. The more support a specification has, the easier it is for everyone to adopt and start using its new features. When the new specification version has enough support, developers can spend more time innovating.

So, if you’re still using Swagger 2, it’s really time to move to OpenAPI 3. Your world will never be the same.

Watch the full presentation

Technical review by Arnaud Lauret.