Skip to content
This repository has been archived by the owner on Sep 6, 2019. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
This branch is 1036 commits ahead, 48 commits behind stoplightio:master.


Failed to load latest commit information.
Latest commit message
Commit time
September 11, 2017 23:15
October 9, 2017 14:03
July 31, 2017 14:29
September 20, 2018 14:28
September 26, 2018 10:52
July 20, 2017 16:27
September 11, 2017 23:29
July 31, 2017 14:22
September 26, 2016 14:41
December 4, 2018 13:34
December 4, 2018 14:37

OAS RAML Converter (DEPRECATED) npm version

Deprecation Notice

This project has been deprecated and is no longer maintained. Please use WebAPI Parser converter instead.

Master Build Status Coverage Status

v0.2.x Build Status Coverage Status

This package helps to convert between different API specifications. It was originally forked from the converter.

Supported Conversions (beta)


1. Online web page

For an online conversion, use:

2. Command line tool

This command needs to be execute after cloning repository,

npm run build

This utility helps you converting local files from your command line.

./lib/bin/converter.js --from OAS20 --to RAML ./path/to/swagger.json
./lib/bin/converter.js --from OAS20 --to RAML ./path/to/swagger.json > output.raml

./lib/bin/converter.js --from RAML --to OAS20 ./path/to/source.raml > swagger.json

Or install globally and then:

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

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

3. As a service

For a REST API of the converter, you can start it in an express server, checkout the oas-raml-converter-service project.

4. As a dependency

Installation (NodeJS or Browser)

npm install --save oas-raml-converter

Initializing a converter

Raml 1.0 to OAS 2.0:

var converter = require('oas-raml-converter');
var raml10ToOas20 = new converter.Converter(converter.Formats.RAML, converter.Formats.OAS20);

OAS 2.0 to Raml 1.0:

var converter = require('oas-raml-converter');
var oas20ToRaml10 = new converter.Converter(converter.Formats.OAS20, converter.Formats.RAML);

The converter detects the input raml format automatically by passing RAML import format, so: Raml 0.8 to OAS 2.0:

var converter = require('oas-raml-converter');
var raml08ToOas20 = new converter.Converter(converter.Formats.RAML, converter.Formats.OAS20);

Raml 0.8 to Raml 1.0:

var converter = require('oas-raml-converter');
var raml08ToRaml10 = new converter.Converter(converter.Formats.RAML, converter.Formats.RAML);

Converting from a file or url

oas20ToRaml10.convertFile('/path/to/swagger.json').then(function(raml) {
  console.log(raml); // raml is raml yaml string
.catch(function(err) {

Converting from a string or json

var myOasString = '...';
oas20ToRaml10.convertData(myOasString).then(function(raml) {
  console.log(raml); // raml is raml yaml string
.catch(function(err) {

Passing options

var options = {
    validate: false, // Parse both input and output to check that its a valid document
    validateImport: false, // Only validate input
    validateExport: false, // Only validate output
    format: 'yaml', // Output format: json (default for OAS) or yaml (default for RAML)
    fs: { ... } // Use a custom file system solver (not yet available)

oas20ToRaml10.convertFile('/path/to/swagger.json', options).then(function(raml) {
  console.log(raml); // raml is raml yaml string
.catch(function(err) {


Contributions are welcome! Please check the current issues to make sure what you are trying to do has not already been discussed.


  1. Fork.
  2. Make changes.
  3. Write tests.
  4. Send a pull request.


Install dependencies:

npm install

Run tests:

npm test

Run eslint to check linting errors:

npm run eslint