Wondering what’s next for npm?Check out our public roadmap! »

    api-spec-converter

    2.12.0 • Public • Published

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

    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
    

    Install

    npm i api-spec-converter

    DownloadsWeekly Downloads

    10,006

    Version

    2.12.0

    License

    MIT

    Unpacked Size

    19.6 MB

    Total Files

    189

    Last publish

    Collaborators

    • avatar
    • avatar