DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations
Building Scalable Real-Time Apps with AstraDB and Vaadin
Register Now

Trending

  • Top Six React Development Tools
  • What Is Envoy Proxy?
  • Building a Flask Web Application With Docker: A Step-by-Step Guide
  • Incident Response Guide

Trending

  • Top Six React Development Tools
  • What Is Envoy Proxy?
  • Building a Flask Web Application With Docker: A Step-by-Step Guide
  • Incident Response Guide
  1. DZone
  2. Software Design and Architecture
  3. Cloud Architecture
  4. 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.

Mitch Dresdner user avatar by
Mitch Dresdner
CORE ·
May. 25, 18 · Interview
Like (3)
Save
Tweet
Share
25.07K Views

Join the DZone community and get the full member experience.

Join For Free

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.

Image title

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 OASSwagger 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.

Image titleSwagger2RamlXfrm

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.

Swagger-Docker-Raml

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.

Image title

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!

JSON Docker (software)

Opinions expressed by DZone contributors are their own.

Trending

  • Top Six React Development Tools
  • What Is Envoy Proxy?
  • Building a Flask Web Application With Docker: A Step-by-Step Guide
  • Incident Response Guide

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com

Let's be friends: