README.md

api-spec-converter

Convert between API description formats such as Swagger and RAML

Currently only supports conversion to OpenAPI(fka Swagger) 2.0 format

You can also use the online version at https://lucybot.github.io/api-spec-converter

Installation

Command Line

npm install -g api-spec-converter

NodeJS

npm install --save api-spec-converter

Browser

bower install --save api-spec-converter

Usage

Command Line

$ api-spec-converter -h

  Usage: api-spec-converter [options] <URL|filename>

  Convert API descriptions between popular formats.

  Supported formats:
    * swagger_1
    * swagger_2
    * api_blueprint
    * io_docs
    * google
    * raml
    * wadl

  Options:

    -h, --help           output usage information
    -V, --version        output the version number
    -f, --from <format>  Specifies format to convert
    -t, --to <format>    Specifies output format
    -c, --check          Check if result is valid spec
    -d, --dummy          Fill missing required fields with dummy data

Example:

$ api-spec-converter https://api.gettyimages.com/swagger/api-docs --from=swagger_1 --to=swagger_2 > swagger.json

NodeJS

Options

• from - source format (see formats below)
• to - desired format (see formats below)
• source - Filename or URL for the source

Simple example:

var Converter = require('api-spec-converter');

Converter.convert({
  from: 'swagger_1',
  to: 'swagger_2',
  source: 'https://api.gettyimages.com/swagger/api-docs',
}, function(err, converted) {
  console.log(converted.stringify());
})

Callback vs Promises

This library has full support for both callback and promises. All async functions return promises but also will execute callback if provided.

var Converter = require('api-spec-converter');

Converter.convert({
  from: 'swagger_1',
  to: 'swagger_2',
  source: 'https://api.gettyimages.com/swagger/api-docs',
})
  .then(function(converted) {
    console.log(converted.stringify());
  });

Advanced features:

var Converter = require('api-spec-converter');
Converter.convert({
  from: 'swagger_1',
  to: 'swagger_2',
  source: 'https://api.gettyimages.com/swagger/api-docs',
})
  .then(function(converted) {
    // [Optional] Fill missing fields with dummy values
    converted.fillMissing();

    // [Optional] Validate converted spec
    return converted.validate()
      .then(function (result) {
        if (result.errors)
          return console.error(JSON.stringify(errors, null, 2));
        if (result.warnings)
          return console.error(JSON.stringify(warnings, null, 2));

        console.log(converted.stringify());
        FS.writeFileSync('swagger2.json', converted.stringify());
      });
  });

Browser

APISpecConverter.convert(...)

Supported Formats

• Swagger 1.x (swagger_1)
• OpenAPI(fka Swagger) 2.0 (swagger_2)
• I/O Docs (io_docs)
• API Blueprint (api_blueprint)
• Google API Discovery (google)
• RAML (raml)
• WADL (wadl)

Conversion Table

from:	swagger_1	swagger_2	io_docs	api_blueprint	google	raml	wadl
to swagger_1	n/a
to swagger_2	✅	n/a	✅	✅	✅	✅	✅
to io_docs			n/a
to api_blueprint				n/a
to google					n/a
to raml						n/a
to wadl							n/a

Contributing

Contributions are welcome and encouraged. See docs/Contributing.md for instructions, tips, and starter projects.