How to migrate from RAML to Open-API 3.0 the easy way!

David Makuni
Oct 12, 2019 · 2 min read

RESTful APIs are the digital glue that connect modern IT systems together and require proper documentation.

Companies often struggle with creation and management of their APIs due to design flaws that appear too late to get fixed at moderate cost. Adequate documentation is also key for API maintenance to establish a common understanding of current and future features among all stakeholders.

Normally you would not create a specification yourself but use an established specification framework instead. OpenAPI Specification and RAML (RESTful API Modelling Language) are the two market leaders in this area.

Open-API vs RAML

Deciding which one you use will also decide what visualiser or editor you can use, a key consideration. If you want to convert existing API documentation (for example to use a different visualisation tool) there is a package which can help you do this called oas-raml-converter-cli.


// Yarn
yarn global add oas-raml-converter-cli
// NPM
npm install -g oas-raml-converter-cli


To run the CLI utility run the following command after installing:

  1. Start the utility via oasraml-cli or oas-raml-converter-cli in the terminal and you will see this:
Choose the type of converter you want to use (enter option 1-5):1) RAML 0.8 > RAML 1.0
2) RAML 0.8 > OAS 2.0
3) RAML 1.0 > OAS 2.0
4) RAML 1.0 > OAS 3.0
5) OAS 2.0 > RAML 1.0
Enter now:

2. After choosing your option select the source file (the utility will check if it exists before continuing):

Enter the source path of the file:

3. Enter a destination path. If the folders do not exist the application will create them. Ensure you have adequate permissions in your target destination:

Enter the destination path for the file:

4. A final prompt before performing the conversion, press (y) to continue or (n) to abort:

Are you sure you want to continue (y/n):

And thats it, your file should now be converted. You will be able to convert any version of Open API to RAML and vice versa as many times as you like!

If you have any comments please write them below, thanks for reading!

David Makuni

Written by

I am an experienced Full Stack React.JS developer who is passionate about technology, economics & automation. LinkedIn:

More From Medium

Also tagged Command Line

Also tagged Command Line

Top on Medium

Ed Yong
Mar 25 · 22 min read


Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade