Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/LucyBot-Inc/api-spec-converter
Convert API descriptions between popular formats such as OpenAPI(fka Swagger), RAML, API Blueprint, WADL, etc.
https://github.com/LucyBot-Inc/api-spec-converter
Last synced: 5 days ago
JSON representation
Convert API descriptions between popular formats such as OpenAPI(fka Swagger), RAML, API Blueprint, WADL, etc.
- Host: GitHub
- URL: https://github.com/LucyBot-Inc/api-spec-converter
- Owner: LucyBot-Inc
- License: mit
- Created: 2015-05-05T18:30:05.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-04-22T21:36:11.000Z (7 months ago)
- Last Synced: 2024-05-17T14:41:54.070Z (6 months ago)
- Language: JavaScript
- Homepage: https://lucybot-inc.github.io/api-spec-converter/
- Size: 21.9 MB
- Stars: 1,091
- Watchers: 22
- Forks: 176
- Open Issues: 104
-
Metadata Files:
- Readme: README.md
- Changelog: Changelog.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - LucyBot-Inc/api-spec-converter - Convert API descriptions between popular formats such as OpenAPI(fka Swagger), RAML, API Blueprint, WADL, etc. (others)
README
# api-spec-converter
> This project is looking for a new maintainer! Let us know if you're interested in taking it over.
[![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