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 FreeJSON 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
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!
Opinions expressed by DZone contributors are their own.
Comments