unicornio8/oas-raml-converter

Converts between OAS and RAML API specifications:

OAS RAML Converter

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

Supported Conversions (beta)

• OAS (Swagger 2.0) -> RAML 1.0: Complete Functional Specification
• RAML 1.0 -> OAS (Swagger 2.0): Complete Functional Specification
• RAML 0.8 -> OAS (Swagger 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

./lib/bin/converter.js --from SWAGGER --to RAML10 ./path/to/swagger.json

Or install globally and then:

oas-raml-converter --from SWAGGER --to RAML10 ./path/to/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 ramlToSwagger = new converter.Converter(converter.Formats.RAML10, converter.Formats.SWAGGER);

OAS 2.0 to Raml 1.0:

var converter = require('oas-raml-converter');
var swaggerToRaml = new converter.Converter(converter.Formats.SWAGGER, converter.Formats.RAML10);

You can tell the converter to detect the input format automatically by passing AUTO format:

var converter = require('oas-raml-converter');
var autoToRaml = new converter.Converter(converter.Formats.AUTO, converter.Formats.RAML10);

Converting from a file or url

swaggerToRaml.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 mySwaggerString = '...';
swaggerToRaml.convertData(mySwaggerString).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)
};

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