Fork of api-spec-converter. Convert API descriptions between popular formats such as OpenAPI(fka Swagger), RAML, API Blueprint, WADL, etc.
Last updated a year ago by itential-ci .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @itentialopensource/api-spec-converter 
SYNC missed versions from official npm registry.


This is a fork of https://github.com/LucyBot-Inc/api-spec-converter, with google-discovery-to-swagger and raml-to-swagger removed due to security vulnerabilities.

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/.


Command Line

Problems? See issue #132

npm install -g api-spec-converter


npm install --save api-spec-converter


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


    -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


$ 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



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

  from: 'swagger_1',
  to: 'swagger_2',
  source: 'https://api.gettyimages.com/swagger/api-docs',
}, function(err, converted) {
  // 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');

  from: 'swagger_1',
  to: 'swagger_2',
  source: 'https://api.gettyimages.com/swagger/api-docs',
.then(function(converted) {

Advanced features:

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

    // [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());


<script src="node_modules/api-spec-converter/dist/api-spec-converter.js"></script>

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


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


Contributions are welcome and encouraged.


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

WRITE_GOLDEN=true npm test


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

Current Tags

  • 2.7.32                                ...           latest (a year ago)

1 Versions

  • 2.7.32                                ...           a year ago
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 1
Last Month 1
Dependencies (17)
Dev Dependencies (15)
Dependents (1)

Copyright 2014 - 2016 © taobao.org |