eduardrosert/api-spec-converter

By eduardrosert

•Updated over 5 years ago

docker image for https://github.com/LucyBot-Inc/api-spec-converter

Image

2.9K

Overview Tags

eduardrosert/api-spec-converter repository overview

⁠api-spec-converter

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

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

⁠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

Tag summary

Recent tags

Content type

Image

Digest

Size

75.1 MB

Last updated

over 5 years ago

docker pull eduardrosert/api-spec-converter