loading...

Convert Swagger 2.0 to OpenAPI 3.0

derberg profile image Lukasz Gornicki ・2 min read

Staying with Swagger 2.0 is like staying with ... still working on a good comparison. Anyway, you should migrate to OpenAPI, and my goal here is not to convince you why. I assume you already made this smart decision, and I just want to make it easier for you.

I did not perform any more in-depth investigation of available tools. There are tools provided by Mermade Software. To be more specific, by Mike Ralphson that is a member of Technical Steering Committee. For me, this is a good reason not to research different tools.

Convert in a Browser

Conversion in a browser is addressed by Kin Lane aka API Evangelist in this thread and the video so watch it and go to https://mermade.org.uk/openapi-converter

Convert in a Terminal

Use swagger2openapi and have fun:

NPM

  1. Install the tool npm install -g swagger2openapi
  2. Run conversion swagger2openapi --yaml --outfile openapi.yaml https://petstore.swagger.io/v2/swagger.json

And that is it. Check your new openapi.yaml file.

NPX

NPX is useful in CI/CD where you do not want to install swagger2openapi globally.

npx -p swagger2openapi swagger2openapi --yaml --outfile openapi.yaml https://petstore.swagger.io/v2/swagger.json

Docker

NPM and NPX is not your thingy? use the Docker image provided by Mike.

#this part "-v ${PWD}:/usr/src/app" mounts the directory where you started "docker run" inside the container where CLI is triggered, this way generated "openapi.yaml" gets into your local drive
docker run --rm -v ${PWD}:/usr/src/app mermade/swagger2openapi swagger2openapi --yaml --outfile openapi.yaml https://petstore.swagger.io/v2/swagger.json

Convert Multiple Files

You most probably have many services, and you need to convert many Swagger files, and you do not want to do it one by one but all at once with a script. You can use Bash and write some script that runs the CLI, but writing Bash scripts is like ... yeah, one day I'll find a good comparison.

Just use swagger2openapi as a library. Go to this repository and try out the sample project that converts multiple files located in directories and subdirectories.

GitHub logo derberg / convert-swagger-to-openapi-playground

Some instructions and sample how to convert Swagger 2.0 files to OpenAPI 3.0

Convert Swagger to OpenAPI Playground

Staying with Swagger 2.0 is like staying with ... still working on a good comparison. Anyway, you should migrate to OpenAPI, and my goal here is not to convince you why. I assume you already made this smart decision, and I just want to make it easier for you.

I did not perform any more in-depth investigation of available tools. There are tools provided by Mermade Software. To be more specific, by Mike Ralphson that is a member of Technical Steering Committee. For me, this is a good reason not to research different tools.

Convert in a Browser

Conversion in a browser is addressed by Kin Lane aka API Evangelist in this thread and the video so watch it and go to https://mermade.org.uk/openapi-converter

Convert in a Terminal

Use swagger2openapi and…

Posted on by:

derberg profile

Lukasz Gornicki

@derberg

An open-source freak that started his career as a tech writer. Then got into development to later become a product owner that because of being an open-source freak started working as dev comm keeper

Discussion

pic
Editor guide