Skip to content

Latest commit

 

History

History
176 lines (144 loc) · 5.98 KB

README.md

File metadata and controls

176 lines (144 loc) · 5.98 KB

api-spec-converter

Share on Twitter

Chat on gitter NPM version Bower version Build status

Code climate 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

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

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.