<commit_before># API Spec Converter [![Build Status](https://travis-ci.org/stoplightio/api-spec-converter.svg)](https://travis-ci.org/stoplightio/api-spec-converter) [![Coverage Status](https://coveralls.io/repos/stoplightio/api-spec-converter/badge.svg?branch=master&service=github)](https://coveralls.io/github/stoplightio/api-spec-converter?branch=master)

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

## 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

```bash
npm install --save api-spec-transformer
```


## Usage

### Convert RAML to OAS (Swagger), from a file.

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

var ramlToSwagger = new transformer.Converter(transformer.Formats.RAML, 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 RAML, from a URL.

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

// Convert swagger to raml, from a url.

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

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 RAML:

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

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

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

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:

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

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

var mySwaggerString = '...';

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


## Development

Install dependencies:
```bash<commit_msg>add supported conversions section<commit_after># API Spec Transformer [![Build Status](https://travis-ci.org/stoplightio/api-spec-converter.svg)](https://travis-ci.org/stoplightio/api-spec-converter) [![Coverage Status](https://coveralls.io/repos/stoplightio/api-spec-converter/badge.svg?branch=master&service=github)](https://coveralls.io/github/stoplightio/api-spec-converter?branch=master)

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

## 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

```bash
npm install --save api-spec-transformer
```


## Usage

### Convert RAML to OAS (Swagger), from a file.

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

var ramlToSwagger = new transformer.Converter(transformer.Formats.RAML, 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 RAML, from a URL.

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

// Convert swagger to raml, from a url.

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

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 RAML:

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

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

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

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:

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

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

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 -> OAS (Swagger 2) * Experimental
- Postman -> RAML 0.8 * Experimental
- Postman -> RAML 1.0 * Experimental

## Development

Install dependencies:
```bash
{'fraction_non_alphanumeric': 0.13670886075949368, 'fraction_numerical': 0.004905063291139241, 'mean_word_length': 4.241293532338308, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 10, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1808961', 'n_tokens_mistral': 2112, 'n_tokens_neox': 2009, 'n_words': 527}