api-spec-converter

Convert API descriptions between popular formats such as OpenAPI(fka Swagger), RAML, API Blueprint, WADL, etc.

Usage no npm install needed!

<script type="module">
  import apiSpecConverter from 'https://cdn.skypack.dev/api-spec-converter';
</script>

README

api-spec-converter

Share on Twitter

Chat on gitter NPM version Build status

Dependency status devDependency status

Convert between API description formats such as Swagger and RAML

Currently only supports conversion to OpenAPI(fka Swagger) 2.0 format, and from OpenAPI 2.0 to OpenAPI 3.0.x

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

Installation

Command Line

Problems? See issue #132

npm install -g api-spec-converter

NodeJS/Browser

npm 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
    * openapi_3
    * 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
    -s, --syntax [syntax]   Specifies output data syntax: json or yaml. Defaults to json
    -o, --order [sortOrder] Specifies top fields ordering: openapi or alpha. Defaults to openapi
    -c, --check             Check if result is valid spec
    -d, --dummy             Fill missing required fields with dummy data

Example:

$ api-spec-converter --from=swagger_1 --to=swagger_2 --syntax=yaml --order=alpha https://raw.githubusercontent.com/LucyBot-Inc/api-spec-converter/master/test/input/swagger_1/petstore/pet.json > swagger.json

NodeJS

Options

  • from - source format (see formats below)
  • to - desired format (see formats below)
  • source - Filename, URL, or JS object 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());
  // For yaml and/or OpenApi field order output replace above line
  // with an options object like below
  //   var  options = {syntax: 'yaml', order: 'openapi'}
  //   console.log(converted.stringify(options));
})

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));

        fs.writeFileSync('swagger2.json', converted.stringify());
      });
  });

Browser

<script src="node_modules/api-spec-converter/dist/api-spec-converter.js"></script>
APISpecConverter.convert(...)

Supported Formats

Conversion Table

from: swagger_1 swagger_2 openapi_3 io_docs api_blueprint google raml wadl
to swagger_1 n/a
to swagger_2 :white_check_mark: n/a :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark:
to openapi_3 :eight_spoked_asterisk: :white_check_mark: n/a :eight_spoked_asterisk: :eight_spoked_asterisk: :eight_spoked_asterisk: :eight_spoked_asterisk: :eight_spoked_asterisk:
to io_docs n/a
to api_blueprint n/a
to google n/a
to raml n/a
to wadl n/a

Key

  • :white_check_mark: - direct conversion
  • :eight_spoked_asterisk: - conversion via swagger_2

Contributing

Contributions are welcome and encouraged.

Testing

Please add a test case if you're adding features or fixing bugs. To run the tests:

npm test

In case you need to override the expected outputs, due to a justified and verified change, run this:

WRITE_GOLDEN=true npm test

Releases

npm run browserify
git commit -a -m "Build browser distribution"
npm version minor # or major/patch
npm publish
git push --follow-tags