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

$3

> Problems? See issue #132
``bash
npm install -g api-spec-converter
`

$3

`bash
npm install --save api-spec-converter
`

Usage

$3

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

$3

$3


* from - source format (see formats below)
* to - desired format (see formats below)
* source - Filename, URL, or JS object for the source

$3

`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));
})
`


$3

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());
});
`


$3


`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());
});
});
`

$3


`js

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

$3

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
`


$3


`
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