Convert between Swagger 2.0 and OAS 3.0–with an API!

Interoperability and data exchange rely on Open Standards—which has been Swagger for the longest time in the API world. With OAS 3.0 becoming more prominent, it’s a good opportunity to read about the differences between OAS 2.0 and 3.0 and remind ourselves that “Swagger” is indeed an outdated term for something we should call “OAS 2.0.”

Version 2.0 (“Swagger files”) are all over the place and we use them for everything. Some tools like Stoplight produce OAS 3.0 documents already, and we all know there are YAML formats and JSON. How do we convert between all of those?

There are a couple of web-based converters, but I’m not a fan of using this through the browser—and I wouldn’t necessarily want everyone to see my API definitions. What if I want an on-premise solution? There’s a couple of libraries and projects on the web but not that easy to consume.

A dockerized API to convert between 2.0 and 3.0 documents

I’ve started a project called Samsa recently, it’s an API in a docker image you can run (almost) anywhere and convert Swagger 2.0 files to OAS 3.0. Or the other way round. It even works if your source file is in YAML and you want JSON. Or the other way round.

You’ll have, of course, a Swagger file that describes the API at http://localhost:8080/swagger and a Postman Collection that gets you started quickly.

Here’s a cURL example: let’s convert a YAML based OAS 3.0 document to a Swagger 2.0 (ok… OAS 2.0) document in JSON format:

curl -s -X POST -d@oas3.yaml "http://localhost:8080/v3tov2"

So this works well! I’m hoping the converter will help with your scenario. OAS 3.0 has a couple of significant improvements over 2.0 and you’ll understand that the converter won’t be able to take all the features into account when you are trying to convert a 3.0 document to 2.0.

Just in case if you’re wondering where the name comes from, Mr. Samsa is the main character in Kafka’s Metamorphosis.