While I was writing the previous article, which is never published, I realized that many do not understand the difference between terms Swagger and OpenAPI (OAS). People use both terms interchangeably. I do not blame them since I had the same doubts.
Swagger allows you to describe the structure of your APIs so that machines can read them.
— SwaggerIO
If you try to google Swagger or OpenAPI, in the most cases, you will end up at SwaggerIO, the official Swagger website. If you ask me, the website has obscured Swagger purpose since day one. Not intentionally, though. Information is not missing, it’s just not presented in a clear and concise manner.
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.
— SwaggerIO
Today, there are many articles on this topic, thus it’s much easier to figure out the difference, but still it is possible to find writings which are intermingling the terms. SwaggerIO is promoting the Swagger as a set of tools, and the OpenAPI as a specification. We could say that the Swagger is used to create OpenAPI specification. Essentially, this statement is not wrong, but it is not the entire truth.
Usage of the terms
Usually, developers use term Swagger in, at least, two contexts:
- to describe a set of tools for implementing the specification. Some tools are Swagger Editor, Swagger UI, Swagger Codegen, etc. It is an ecosystem.
- to describe the specification of version 2.*.*
Other widely used terms are Swagger 2, Swagger Specification 2, OpenAPI Specification 2, etc.
Developers use the term OpenAPI Specification 3 mostly in a single context:
- to describe the specification of version 3.*.*. Community refers as OAS, OAS3, OpenAPI Spec, OpenAPI 3 Specification, etc. They adopted OpenAPI 3 as the successor of Swagger Specification 2.
Reasons
Swagger and OpenAPI are close friends for a reason. History is the key ingredient here.
SmartBear company maintains Swagger. In November 2015, The Linux Foundation announced they are creating, together with SmartBear, Google, Microsoft, Paypal, and few other companies, a new organization, OpenAPI Initiative. The primary task of the initiative was to extend the Swagger specification.
A few months afterward, the initiative renamed Swagger to OpenAPI specification. The initiative cloned the code to the new repository. From that point, individuals have used both terms in various contexts.
Final word
Swagger used to be an all-in-one, specification and toolset. Today, Swagger is a toolset. OpenAPI is a specification. That’s it.
It’s nice to know the difference. Yet whichever term you use, the other side will understand you — in the end, that is the only thing that matters.