What’s the Difference Between Swagger and OpenAPI?

Posted in

If you’re working in the API space, no matter the capacity, you’ve probably heard people talk about Swagger and OpenAPI. As this post indicates, there’s some confusion around how these terms should be used.

A Swagger blog post from 2017 explains that the reason for these terms existing alongside each other is that there was a transition in 2015 from Swagger to OpenAPI. The short version of this story is this:

Although the terms once referred to the same thing, they can no longer be used interchangeably…even though some people still do. In 2021, OpenAPI refers to the industry-standard specification for RESTful API design. Swagger refers to a set of SmartBear tools.

In this post, we’ll be covering all of that much more detail, looking at the history of Swagger and where its legacy fits in the story of the OpenAPI Initiative and its OpenAPI Specification.

Define: Swagger (and History)

SmartBear maintains the Swagger tools at Swagger.io.

According to Tony Tam, Swagger is “a simple contract for an API that contains everything needed to produce or consume an API…Twenty pages or so, and that’s it.” And Tam should know, since he created Swagger.

Development on the ideas behind Swagger began in the early 2010s as the brainchild of Tam when he was the technical co-founder of a dictionary system called Wordnik. He would later become the CTO of Wordnik and move on to be the CEO of Reverb Technologies, Wordnik’s parent company.

It’s worth knowing a little about Tam’s history because it demonstrates Swagger’s relatively speaking, humble beginnings. The system was developed not to be an all-encompassing methodology but as the UI for Wordnik’s own API. Everything that came afterward was, to a certain extent, a happy accident.

People engaged with Wordnik’s portal and clamored for open-source status, and adoption of the framework by other companies took off. In early 2015 Swagger was acquired from Reverb by SmartBear, with some big changes to come later in that year.

Define: OpenAPI (and History)

OpenAPI Specification is the vendor-neutral industry-standard API spec supported by the Linux Foundation.

Towards the end of 2015, SmartBear launched the OpenAPI Initiative with sponsorship from the Linux Foundation. The Swagger specification was adopted by the group and rebranded as OpenAPI Specification in the process.

Founding members of the OpenAPI Initiative included huge names like Google, Apigee, PayPal, Microsoft, Capital One, Intuit, and others. Tam remained involved with Swagger, now OpenAPI, on the Technical Oversight Board driving technical aspects of the spec for almost two years and currently works at Apple, handling iCloud developer experience.

As per the Swagger site, “The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.”

The OpenAPI Specification, now on v3.1.0, is essentially a set of best practices that refer to versioning, formatting, document structure, schema, and so on in the context of APIs, with the aim of building consistency and reliability.

Swagger vs. OpenAPI

As a result of all the above, it’s now correct to talk about OpenAPI specifications rather than using Swagger in that context. The use of the term Swagger persists in the API space, however, and for good reason. As of 2021, we can think of it like this:

  • OpenAPI = The specification itself, formerly known as Swagger specification
  • Swagger = Tools used in the implementation of OpenAPI

There’s a range of tools available that use the Swagger moniker, including Swagger Editor, Swagger UI, Swagger Codegen, Swagger Inspector, and various others. A full list of tools often used in conjunction with OpenAPI is available on the OpenAPI Initiative’s GitHub.

One post on the Swagger blog poses the following question: why haven’t Swagger tools changed their name to OpenAPI? You can read a lengthy answer over there, but the short version is that, while SmartBear donated the specification itself to the OpenAPI Initiative, they didn’t have the authority to rebrand the core tools associated with it.

You’ll notice, however, that most tools in the list above now reference OpenAPI in their names (e.g. OpenAPI 3 Viewer) rather than Swagger. In other words, all Swagger tools utilize OpenAPI but not all OpenAPI tools — e.g., Apicurio Studio, Lincoln, API Sprout, Fusio, Gen — are Swagger tools, which is a distinction that’s worth noting.

OpenAPI and Swagger’s Legacy

The OpenAPI Initiative governs the OpenAPI Specification.

With those big names in play — Google, Microsoft, PayPal, etc. — within the OpenAPI Initiative, it’s at least worth asking the following question: is the acquisition* of Swagger an example of an open-source project being snapped up and gated off by massive brands?

  • We use the term loosely here, as the transition from Swagger to OpenAPI wasn’t quite an acquisition in traditional terms.

In a word, no. As its name suggests, the OpenAPI Specification remains…well, open. Nor has iteration slowed as a result of the transition: Swagger first released in 2011, with 1.1 following in 2012 and v2.0 coming in 2014. OpenApi 3.0 was released in 2017, with patches through to 3.0.3 following in 2017, 2018, and 2020. Version 3.1.0 was released at the beginning of 2021.

Plus, Tam highlights the value of the change in the YouTube video linked above:

“I think it’s an important step for something like Swagger to move into this OpenAPI Initiative so that it can follow the trends of the industry, people can work with it and bring their knowledge to what it needs to do in the future (hopefully without messing it up), and also sharing the burden of the actual work.”

One of the biggest hurdles of standardization is demonstrating that a system has longevity and has established enough of a presence to capture — or have the potential to capture — a big enough share of the market.

The OpenAPI Initiative aims to address those concerns and seems to have done so to this point, while handling Swagger’s legacy with enough respect to avoid an outcry from those who supported it before it was the OpenAPI Specification.

It’s impossible to say what the future holds, but the API industry seems to have strongly embraced OpenAPI thus far.

Resources for Further Reading