How to Convert Swagger 2.0 to OpenAPI 3.0 format

Swagger 2.0 and OpenAPI 3.0 are both standard definitions on how we can present our REST API endpoints. These definitions serve as a bridge to help both the developers and non-tech personnel to efficiently understand the capabilities of system services without the need to analyse source code.

Swagger 2.0

In 2014, Swagger 2.0 is released by swagger community as a set of definitions. Hence, this allows API designing to be done in a form of written specification.

Swagger 2.0 Documentation: Doc

OpenAPI 3.0

OpenAPI 3.0 (or also known as Swagger 3.0) is a set of definitions released in 2017 after swagger donated the specification to OPENAPI Initiative. Thus, this make OpenAPI 3.0 a more improved version over the Swagger 2.0 definition.

OpenAPI 3.0 Documentation: Doc

Convert Swagger to OpenAPI

Although OpenAPI have been released since 2017, swagger is still widely used in the community. Most plugins found also mostly seems to only work with Swagger 2.0.

On top of that, developers sometime need to use multiple plugins to work together but some seems to work with Swagger format while others work with OpenAPI format making them hard to integrate.

Thus, one solution available is to convert from one to another format by using a convertor. Here, we will illustrate by using the command line version of api-spec-converter to perform this conversion.

Step 1: Install NPM package

npm install -g api-spec-converter

Step 2: Check ‘api-spec-converter’ running in command line

You can use npx as a package runner to run in command line since this is an npm package. See my other blog post here on how to can setup npx to execute npm packages via command line.

3. Define origin specification

We will use ‘swagger_2’ as the input format.

4. Define resulting specification and the syntax

Since we are converting to openapi 3.0, we will use ‘openapi_3’ as the output format.

For the syntax, it supports yaml and json. We will use ‘yaml’ in this example.

5. Execution

Put in the parameters and set the input and output file and it will produce the openAPI specification file.

npx api-spec-converter --from=swagger_2 --to=openapi_3 --syntax=yaml https://petstore.swagger.io/v2/swagger.json > swagger.json

Although you have only seen the conversion to openAPI 3.0, this plugin also support other conversions too.

Conclusion

Being able to convert specification from one version to the other automatically will greatly improve the efficiency of your work. So far this has been working well for me. However, it will also be good to do a check to confirm if your input specification are fully translated into the converted specification just to be sure!

There should be others out there where I have not seen. Feel free to share them in the comments below and I will look into them too!