This year marked the official release of OpenAPI 3.0, the latest version of the OpenAPI specification.
For those involved in API development, the release of OAS 3.0 is, well... kind of a big deal.
Why? One of the most notable reasons why the release is so important is that OpenAPI 3.0 is the first official release of the specification since it was donated to the OpenAPI Initiative by SmartBear Software and renamed from the Swagger Specification to OpenAPI specification in 2015.
Before we go into some of the reasons why OpenAPI 3.0 is so important to the API space, it’s important to first clear up some questions about OpenAPI and what it means for Swagger.
In the last two years there have been a lot of questions about the change from Swagger to OpenAPI. And there has also been a lot of confusion about the difference between OpenAPI and Swagger, when to use one name over the other, and what the relationship is between OpenAPI and Swagger.
Let's start with clarifying Swagger vs OpenAPI
The easiest way to understand the difference is:
- OpenAPI = Specification
- Swagger = Tools for implementing the specification
The OpenAPI is the official name of the specification. The development of the specification is fostered by the OpenAPI Initiative, which involves more the 30 organizations from different areas of the tech world — including Microsoft, Google, IBM, and CapitalOne. Smartbear Software, which is the company that leads the development of the Swagger tools, is also a member of the OpenAPI Initiative, helping lead the evolution of the specification.
Swagger is the name associated with some of the most well-known, and widely used tools for implementing the OpenAPI specification. The Swagger toolset includes a mix of open source, free, and commercial tools, which can be used at different stages of the API lifecycle.
These tools include:
- Swagger Editor: Swagger Editor lets you edit OpenAPI specifications in YAML inside your browser and to preview documentations in real time.
- Swagger UI: Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from an OAS-compliant API.
- Swagger Codegen: Allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Spec.
- Swagger Parser: Standalone library for parsing OpenAPI definitions from Java
- Swagger Core: Java-related libraries for creating, consuming, and working with OpenAPI definitions
- Swagger Inspector (free): API testing tool that lets you validate your APIs & generate OpenAPI definitions from an existing API
- SwaggerHub (free and commercial): API design and documentation, built for teams working with OpenAPI.
Since the Swagger tools were developed by the team involved in the creation of the original Swagger Specification, the tools are often still viewed as being synonymous with the spec. But the Swagger tools are not the only tools that are available for implementing the OpenAPI Specification. There are a wide variety of API design, documentation, testing, management, and monitoring solutions that support version 2.0 of the specification, and are actively working on adding 3.0 support.
You can find the full list of tools that offer support for the latest version of the OpenAPI specification on GitHub.
Why haven’t the Swagger tools changed their name to OpenAPI?
The Swagger ecosystem has always been comprised of the Specification and the core open source tooling around it, most famously the Swagger UI, Swagger Editor, and Swagger Codegen. A big reason why the Specification became so widely adopted was because of the tooling that lived alongside it.
SmartBear donated the Specification, but the popular open source Swagger tooling still retained the original branding due to the strong association developers, tech writers, testers and designers had with the tooling. The specification is not, and has never been solely associated with the Swagger tools. In fact, the decision to donate the specification and form the OpenAPI Initiative is to ensure that OpenAPI remains completely vendor neutral. It’s why we are thrilled to see so many across the API space, including companies that also support other definition formats — like API Blueprint and RAML — join the Initiative.
The Swagger team remains focused on building the most powerful, and easy to use tooling for designing, documenting, developing, and testing APIs using the OpenAPI Specification, and will continue to grow and evolve our toolset to support the OpenAPI. These tools will continue to maintain the Swagger name. Swagger.io, the online home of the Swagger tooling and the open source Swagger projects, will also continue to be a go-to place to learn about the Swagger tools, and we will also continue to contribute to the knowledge around the OpenAPI Specification, through trainings, tutorials, webinars and documentation for working with OpenAPI.
Understanding the OpenAPI and Swagger Communities
While there will always be overlap between people that contribute to the OpenAPI, and those that contribute to the Swagger tooling, these two communities are independent from each other.
As mentioned in this article, the OpenAPI Initiative is an open, vendor-neutral organization that welcomes involvement from anyone that wants to help evolve or leverage the specification in their API development. Organizations are invited to join the growing list of members contributing to the Specification, and individuals are welcome to participate by sharing ideas and feedback on GitHub or attending one of the many OAS meetups held at locations around the world each month. Learn more about how to contribute here.
The Swagger tooling has a community of its own, focused on helping improve some of the existing Swagger projects, and introduce new ideas and feature requests. The Swagger community is fostered by the team at SmartBear Software, which invests in the development of the open source Swagger tools, but is also driven by the contributions of the thousands of Swagger users located around the world. If you want to join the Swagger Community, we invite you to find us on GitHub or join the Swagger API Meetup group. You can also find the latest news and updates on the Swagger blog or @SwaggerAPI on Twitter.
Looking forward to a bright future for OpenAPI
We are looking forward to seeing OpenAPI becoming a name that everyone in the API space recognizes, and we’re thrilled to be part of the growing community of OpenAPI Initiative members.
Hopefully this article helped clarify some of the questions around OpenAPI, and its relationship with Swagger.
To recap:
- The Specification was renamed to the OpenAPI Specification in 2015. OpenAPI 3.0 is the latest version of the specification.
- The Swagger tools, which are supported by SmartBear Software, are among the most popular tools for implementing the OpenAPI Specification, and will continue to maintain the Swagger name (Swagger Editor, Swagger UI, SwaggerHub, etc.)
- There are hundreds of other open source and pro tools, not related to Swagger, that support the OpenAPI 2.0 Specification, and the list of tools supporting 3.0 is continuing to grow.
- OpenAPI and Swagger both have open source communities, and welcome all contributors to join to share their ideas and get involved.
If you have a colleague, friend, or anyone else that’s working with APIs that still has some of these questions, we hope you’ll share this post. The Swagger team will be working hard to help clarify the relationship between Swagger and OpenAPI, and we hope you will too!
Getting Started with Swagger: An Introduction to OAS & Swagger Tools
Join us for a free training on November 14, which will introduce the Swagger tool ecosystem and the OpenAPI Specification. Learn more.