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.github.io/api-spec-converter

Installation

Command Line

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

  Fields Ordering:
    By default fields in the output file will be ordered as they appear 
    in the  OpenApi specification page Swagger Object section.
    https://swagger.io/specification/#swagger-object-14
    
    They can also be alphabetically ordered by using the -o or --order flag.
    If the flag is set to 'alpha', then the fields will be sorted in the A to Z order.
    
    If not set or set to 'openapi' they will be sorted as follow.
    OpenApi fields order:
      * swagger
      * info
      * host
      * basePath
      * schemes
      * consumes
      * produces
      * paths
      * definitions
      * parameters
      * responses
      * securityDefinitions
      * security
      * tags
      * externalDocs

Example:

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

# Yaml output
$ api-spec-converter https://api.gettyimages.com/swagger/api-docs --from=swagger_1 --to=swagger_2 --syntax=yaml > swagger.yaml

# Json output with alpha field order
$ api-spec-converter https://raw.githubusercontent.com/LucyBot-Inc/api-spec-converter/master/test/input/swagger_1/petstore/pet.json --from=swagger_1 --to=swagger_2 --order=alpha > 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());
  // 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));

        console.log(converted.stringify());
        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	✅	n/a	✅	✅	✅	✅	✅	✅
to openapi_3	✳️	✅	n/a	✳️	✳️	✳️	✳️	✳️
to io_docs				n/a
to api_blueprint					n/a
to google						n/a
to raml							n/a
to wadl								n/a

Key

• ✅ - direct conversion
• ✳️ - conversion via swagger_2

Contributing

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