Open API 3.0 vs Swagger 2.0
Swagger is one of the largest and widely used open source framework for API developers to design, build, develop and consume REST APIs. Swagger specification facilitates creating RESTful contract of your API, including all of its resources definitions, available endpoints, operation parameters, authentication mechanisms, contract information andlicense etc in a readable format. Tools like swagger-editor (Web-Based editor for creating, editing, validating and testing OpenAPI\Swagger definitions), swagger-ui (Web-Based interface for visualizing and testing OpenAPI\Swagger definitions) which come along with swagger spec will ease your life in API developer’s world.
API developers have been using Swagger 2.0 spec to define APIs over past few years. Later it has been donated to Linux foundation and named as Open API specification and a new swagger spec was released with lots of new features and improvements as Open API 3.0. Compared to Swagger 2.0, Open API specification comes in more modular and reusable approach to defining the API and it is more powerful, when it comes to describing the request response models and underlying security information.
Let’s take a closer look at what are new in Open API, what are the structural improvements, and how to migrate from Swagger 2.0 to Open API 3.0.
Metadata Changes
All references of swagger have been changed to openapi. Thus swagger 2.0 definition version has to be changes as follows.
"swagger": "2.0" --> "openapi": "3.0.0"Structural Changes
API Endpoint URL Definition
In Swagger 2.0, the API endpoint URL definition is broken into 3 components : host, basePath and schemas and the endpoint URL is a combination of these component values. According to this spec, you can define only one endpoint URL for a given API.
"host": "petstore.swagger.io",
"basePath": "/v1",
"schemes": [
"http"
]But in OpenAPI 3.0, you are allowed to define multiple URLs
Now, you can have multiple “URLs”, and they can be defined anywhere (meaning you can have just one at the base like before, or a specific endpoint can have its own server if the base URL is different). Additionally, path templating is now allowed. In OpenAPI 3, this was only allowed in the actual endpoint URLs. You define the templates with a “variable” property.
References