Converting Swagger to RAML
Converting Swagger to RAML
Read this tutorial in order to learn how to experiment with some basic conversions between swagger and RAML as well as explore some tooling using cool technologies.
Join the DZone community and get the full member experience.Join For Free
The State of API Integration 2018: Get Cloud Elements’ report for the most comprehensive breakdown of the API integration industry’s past, present, and future.
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.
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
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.
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.
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
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
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.
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.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!
Opinions expressed by DZone contributors are their own.