# api-spec-converter > Convert API descriptions between popular formats such as OpenAPI(fka Swagger), RAML, API Blueprint, WADL, etc. Latest version **2.12.0** (published 2021-02-09) · MIT license · 0 weekly downloads ## Install ```sh npm install api-spec-converter pnpm add api-spec-converter yarn add api-spec-converter bun add api-spec-converter ``` Provides the command `api-spec-converter`. ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; large bundle. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 2.12.0 | | Published | 2021-02-09 | | First published | 2015-05-05 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Node | >=6.0.0 | | Dependencies | 20 | | Unpacked size | 18.7 MB | | Known vulnerabilities | 0 (+2 in 2 direct dependencies) | | Install scripts | no | | Maintainers | bobby-brennan, i1g | | Keywords | API, REST, Restful, convert, converter, OpenAPI, OpenAPI Specification, Swagger, RAML, Blueprint, API Blueprint, GoogleDiscovery, WADL, I/O Docs | ## Links - npm: https://www.npmjs.com/package/api-spec-converter - Repository: https://github.com/lucybot/api-spec-converter - Issues: https://github.com/lucybot/api-spec-converter/issues - npm.io page: https://npm.io/package/api-spec-converter ## Dependencies (20) - [sway](https://npm.io/package/sway.md) ^2.0.5 - [urijs](https://npm.io/package/urijs.md) ^1.19.5 - [lodash](https://npm.io/package/lodash.md) ^4.17.19 - [xml2js](https://npm.io/package/xml2js.md) ^0.4.23 - [js-yaml](https://npm.io/package/js-yaml.md) ^3.14.0 - [request](https://npm.io/package/request.md) ^2.88.2 - [bluebird](https://npm.io/package/bluebird.md) ^3.7.2 - [traverse](https://npm.io/package/traverse.md) ^0.6.6 - [commander](https://npm.io/package/commander.md) ^2.20.0 - [drafter.js](https://npm.io/package/drafter.js.md) ^2.6.7 - [source-map](https://npm.io/package/source-map.md) 0.6.0 - [raml-parser](https://npm.io/package/raml-parser.md) ^0.8.18 - [apib2swagger](https://npm.io/package/apib2swagger.md) ^1.9.0 - [composite-error](https://npm.io/package/composite-error.md) ^0.1.1 - [raml-to-swagger](https://npm.io/package/raml-to-swagger.md) ^1.1.0 - [swagger2openapi](https://npm.io/package/swagger2openapi.md) 2.9.* - [deep-sort-object](https://npm.io/package/deep-sort-object.md) ^1.0.2 - [lodash.clonedeep](https://npm.io/package/lodash.clonedeep.md) ^4.5.0 - [swagger-converter](https://npm.io/package/swagger-converter.md) ^1.5.1 - [google-discovery-to-swagger](https://npm.io/package/google-discovery-to-swagger.md) ^2.0.0 ## Alternatives - [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads - [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads - [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads - [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads - [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads ## Recent versions - 2.12.0 (latest) — 2021-02-09 - 2.11.4 — 2021-01-28 - 2.11.2 — 2020-08-27 - 2.11.1 — 2020-07-01 - 2.11.0 — 2020-01-07 - 2.10.2 — 2019-11-08 - 2.10.1 — 2019-09-11 - 2.10.0 — 2019-08-26 - 2.9.1 — 2019-07-25 - 2.9.0 — 2019-07-19 - 2.8.3 — 2019-04-30 - 2.8.1 — 2019-04-12 - 2.8.0 — 2019-04-11 - 2.7.33 — 2019-04-11 - 2.7.32 — 2019-03-25 - … 57 more at https://npm.io/package/api-spec-converter/versions ## README # api-spec-converter [![Share on Twitter][twitter-image]][twitter-link] [![Chat on gitter][gitter-image]][gitter-link] [![NPM version][npm-image]][npm-link] [![Build status][travis-image]][travis-link] [![Dependency status][deps-image]][deps-link] [![devDependency status][devdeps-image]][devdeps-link] Convert between API description formats such as [Swagger](http://swagger.io/) and [RAML](http://raml.org/) **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](https://github.com/LucyBot-Inc/api-spec-converter/issues/132) ```bash npm install -g api-spec-converter ``` ### NodeJS/Browser ```bash npm install --save api-spec-converter ``` ## Usage ### Command Line ```bash $ api-spec-converter -h Usage: api-spec-converter [options] 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 Specifies format to convert -t, --to 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: ```bash $ 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: ```js 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. ```js 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: ```js 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 ```js APISpecConverter.convert(...) ``` ## Supported Formats * [Swagger 1.x](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md) (swagger_1) * [OpenAPI(fka Swagger) 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) (swagger_2) * [OpenAPI 3.0.x](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) (openapi_3) * [I/O Docs](https://github.com/mashery/iodocs) (io_docs) * [API Blueprint](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md) (api_blueprint) * [Google API Discovery](https://developers.google.com/discovery/v1/reference/apis) (google) * [RAML](http://raml.org/spec.html) (raml) * [WADL](http://www.w3.org/Submission/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: ```bash npm test ``` In case you need to override the expected outputs, due to a justified and verified change, run this: ```bash 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 ``` [twitter-image]: https://img.shields.io/twitter/url/http/lucybot.github.io/api-spec-converter.svg?style=social [twitter-link]: https://twitter.com/intent/tweet?text=Convert+between+API+description+formats+such+as+Swagger+and+RAML:&url=http%3A%2F%2Flucybot.github.io%2Fapi-spec-converter [gitter-image]: https://img.shields.io/gitter/room/lucybot/api-spec-converter.svg [gitter-link]: https://gitter.im/lucybot/api-spec-converter [npm-image]: https://img.shields.io/npm/v/api-spec-converter.svg [npm-link]: https://npmjs.org/package/api-spec-converter [travis-image]: https://img.shields.io/travis/LucyBot-Inc/api-spec-converter.svg [travis-link]: https://travis-ci.org/LucyBot-Inc/api-spec-converter [deps-image]: https://img.shields.io/david/lucybot/api-spec-converter.svg [deps-link]: https://david-dm.org/lucybot/api-spec-converter [devdeps-image]: https://img.shields.io/david/dev/lucybot/api-spec-converter.svg [devdeps-link]: https://david-dm.org/lucybot/api-spec-converter#info=devDependencies --- _Source: https://npm.io/package/api-spec-converter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._