README.md

API Spec Transformer

This package helps to convert between different API specifications. It currently supports OAS (Swagger 2), RAML 0.8, RAML 1.0, and Postman collections.

This package is used in production @ https://stoplight.io. If you are using this package in production, please let us know and we will link you.

Note

A prior version of this library was available, but not published on NPM. If you are directly referencing the git URL in your package.json files, please update them to use the api-spec-transformer package name, instead of https://github.com/stoplightio/api-spec-converter. We will be re-naming the git repository to https://github.com/stoplightio/api-spec-transformer in the near future.

Installation

NodeJS or Browser

npm install --save api-spec-transformer

Usage

Convert RAML1.0 to OAS (Swagger), from a file.

var transformer = require('api-spec-transformer');

var ramlToSwagger = new transformer.Converter(transformer.Formats.RAML10, transformer.Formats.SWAGGER);

ramlToSwagger.loadFile('/source/raml.yaml', function(err) {
  if (err) {
    console.log(err.stack);
    return;
  }

  ramlToSwagger.convert('yaml')
    .then(function(convertedData) {
      // convertedData is swagger YAML string
    })
    .catch(function(err){
      console.log(err);
    });
});

Convert OAS (Swagger) to RAML1.0, from a URL.

var transformer = require('api-spec-transformer');

// Convert swagger to raml, from a url.

var swaggerToRaml = new transformer.Converter(transformer.Formats.SWAGGER, transformer.Formats.RAML10);

swaggerToRaml.loadFile('http://petstore.swagger.io/v2/swagger.json', function(err) {
  if (err) {
    console.log(err.stack);
    return;
  }

  swaggerToRaml.convert('yaml')
    .then(function(convertedData) {
      // convertedData is a raml YAML string
    })
    .catch(function(err){
      console.log(err);
    });
});

Convert unknown input to RAML1.0:

You can tell the converter to detect the input format automatically (by passing AUTO format), it will detect the right format for the input.

var transformer = require('api-spec-transformer');

var myConverter = new transformer.Converter(transformer.Formats.AUTO, transformer.Formats.RAML10);

swaggerToRaml.loadFile('http://petstore.swagger.io/v2/swagger.json', function(err) {
  // Will identify the input as swagger - the rest is the same as above.
});

Load a string:

var transformer = require('api-spec-transformer');

var swaggerToRaml = new transformer.Converter(transformer.Formats.SWAGGER, transformer.Formats.RAML10);

var mySwaggerString = '...';

swaggerToRaml.loadData(mySwaggerString)
  .then(function() {
    // Do the converstion, as in the first two examples.
  });

Supported Conversions

• OAS (Swagger 2) -> RAML 0.8
• OAS (Swagger 2) -> RAML 1.0
• RAML 1.0 -> OAS (Swagger 2)
• RAML 0.8 -> OAS (Swagger 2)
• Postman Collection 1.0 -> OAS (Swagger 2) * Experimental
• Postman Collection 1.0 -> RAML 0.8 * Experimental
• Postman Collection 1.0 -> RAML 1.0 * Experimental

Development

Install dependencies:

npm install

Run tests:

npm test

Run eslint to check linting errors:

gulp lint

Contributing

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.