aiskov/oas-raml-converter

Converts between OAS and RAML API specifications:

OAS RAML Converter

Master

v0.2.x

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

Supported Conversions (beta)

• OAS (OAS 2.0) -> RAML 1.0: Complete Functional Specification
• RAML 1.0 -> OAS (OAS 2.0): Complete Functional Specification
• RAML 1.0 -> OAS (OAS 3.0): Complete Functional Specification
• RAML 0.8 -> OAS (OAS 2.0)
• RAML 0.8 -> RAML 1.0

Using

1. Online web page

For an online conversion, use: https://mulesoft.github.io/oas-raml-converter.

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) {
  console.error(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) {
  console.error(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) {
  console.error(err);
});

Contributing

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

Steps

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

Develop

Install dependencies:

npm install

Run tests:

npm test

Run eslint to check linting errors:

npm run eslint