Converting Swagger to RAML

JSON Tooling and Model Conversion

This article will help you experiment with some basic conversions between Swagger and RAML and explore some tooling using some cool technologies.

JSON Tooling and Conversion Experiments

• Standalone NPM converter
• Conversion using a Docker container
• Converting YAML to JSON with a Go utility
• Using jq for XPath like querying of JSON

As you can see from the list above, we have our work cut out for us, so let's roll up our sleeves and get to work!

Open API Specification (OAS)

Swagger aka OAS

Swagger and OAS will be used interchangeably in this tutorial.

Conversion Examples

This article assumes some basic familiarity with modeling JSON API's using Swagger and RAML. For those needing a bit of a refresher, please refer to the links below.

Refresher on Swagger and RAML

Click for RAML tutorial

Click for Swagger tutorial

My earlier DZone article Zero Code REST With json-server has instructions to help you install and get started with NPM and HTTPie if you're not already familiar.

With those packages installed, we can add the other necessary components.

In the steps below, we'll be installing the necessary dependencies for getting started.

Mulesoft OAS RAML Converter

OAS RAML Converter is a Mulesoft project that you can use for OAS/RAML conversions.

We'll clone the git project, install dependencies, build the javascript project, and manually run the converter.

Clone Repo and Build Converter

git clone https://github.com/mulesoft/oas-raml-converter.git

npm install
npm run build

With the OAS RAML Converter installed, let's run a conversion from Swagger to RAML. In our examples, we'll use the Petstore swagger.json, so let's download that next.

Download swagger.json, Start Converter

http --download http://petstore.swagger.io/v2/swagger.json

node lib\bin\converter.js --from OAS20 --to RAML ./swagger.json > petstore.raml

Proxy support NOTE: --proxy=http:http://proxy.foo.bar:80

If you're behind a firewall, you may need to add the proxy switch above to the HTTPie command line with your proxy server address.

If all went well, the swagger.json was converted into petstore.raml.

Mulesoft hosts an online conversion website if you prefer not to install the local Javascript component.

If you would like to install the converter globally, run the commands below.

npm install -g oas-raml-converter

oas-raml-converter --help

Converting Between Swagger and OAS.

oas-raml-converter --from OAS20 --to RAML ./path/to/swagger.json
oas-raml-converter --from OAS20 --to RAML ./path/to/swagger.json > petstore.raml

oas-raml-converter --from RAML --to OAS20 ./path/to/petstore.raml > swagger.json

Be sure to use lib\bin\converter.js if you didn't install oas-raml-converter globally.

Mulesoft Docker Converter

Mulesoft also has a Docker version of the converter that you can learn more about here.

Cloning the Repository and Starting the Docker Container.

git clone https://github.com/mulesoft/oas-raml-converter-service

docker build -t oas-raml-converter:0.1 .

docker run -i -p 3000:3000 -t oas-raml-converter:0.1 /bin/bash

With the docker container running and firewall port 3000 open if you're running remote, let's convert our earlier swagger.json file into RAML.

Using the Docker Converter to Convert OAS to RAML

http POST YOUR_DOCKER_IP_ADDRESS:3000/swagger/to/raml Content-type:text/plain @swagger.json > petstore.raml

Tooling Examples

Using JSON Query (jq)

JSON Query is described as a flexible, lightweight command line processor for performing
Xpath like queries on JSON data. After using the link above to install it, let's run some simple queries on our swagger.json file.

Verify jq Was Properly Installed

jq --help

Display current version and commandline options

When you use the Windows type or Linux cat command to display *swagger.json*, you'll notice that the entire file is on a single line. To pretty-print the file, we can use the _jq_ identity function.

Pretty-print swagger.json

jq . swagger.json

You can also use jq to extract snippets of JSON or perform a myriad of mathematical and utility functions on the data.

See jq manual here.

Extract a JSON Snippet

jq ".tags" swagger.json

Extract an Element

jq ".tags[0].name" swagger.json

Escape Special Characters to Handle JSON Paths

jq ".paths.\"/pet\".post" swagger.json

Produces a JSON snippet of the /pet URI for a POST operation. The slash
is a special character in jq and needs to be escaped with the quotes.

Converting YAML to JSON

Sometimes you may find that you have the YAML version of a Swagger API specification, which you need the JSON equivalent for in order to generate RAML. Here's a nifty conversion utility that is written in Golang, which can be used to generate the JSON schema.

You'll need to clone the git repository to your GOPATH, build, and install. For a quick start guide to getting up and running with Go, see this turorial here.

Cloning the Repository and Installing theGolangConverter

cd %GOPATH%\src

go get -u github.com/wakeful/yaml2json

cd yaml2json

go build

go install

yaml2json -version

GOPATH\bin will need to be in your PATH

Converting a YAML File to JSON

yaml2json PATH_TO_YOUR\file.yaml | jq . > PATH_TO_YOUR\file.json

There we have it, in this example, we pipe the output to JSON Query using an identity function to prettify the output and then redirect the output to our new JSON file.
This concludes our brief examples with conversions and tooling.
I hope you enjoyed reading this article as much as I have enjoyed writing it. I'm looking forward to your comments!