swagger2openapi
![logo](https://github.com/Mermade/swagger2openapi/blob/master/docs/logo.png?raw=true)
![Greenkeeper badge](https://badges.greenkeeper.io/Mermade/swagger2openapi.svg)
Convert Swagger 2.0 definitions into OpenApi 3.0.x
Currently tracking v3.0.0
Usage:
swagger2openapi [options] [filename|url]
Options:
--warnProperty Property name to use for warning extensions
[string] [default: "x-s2o-warning"]
--version Show version number [boolean]
-c, --components output information to unresolve a definition [boolean]
-d, --debug enable debug mode, adds specification-extensions [boolean]
-e, --encoding encoding for input/output files [string] [default: "utf8"]
-h, --help Show help [boolean]
-i, --indent JSON indent to use, defaults to 4 spaces [string]
-o, --outfile the output file to write to [string]
-p, --patch fix up small errors in the source definition [boolean]
-r, --resolve resolve external references [boolean]
-u, --url url of original spec, creates x-origin entry [string]
-v, --verbose increase verbosity [count]
-w, --warnOnly Do not throw on non-patchable errors, add warning extensions
[boolean]
-y, --yaml read and write YAML, default JSON [boolean]
or use the APIs:
var converter = require('swagger2openapi');
var options = {};
converter.convertObj(swagger, options, function(err, options){
});
var validator = require('swagger2openapi/validate.js');
var options = {};
validator.validate(openapi, options, function(err, options){
});
See here for complete documentation of the options
object.
Or use the online version which also includes its own API.
Browser Support
See initial documentation.
Features
OpenAPI 3.0.x validation
The testRunner
harness can also be used as a simple validator if given one or more existing OpenAPI 3.x definitions. The validator (however it is called) uses WHATWG URL parsing if available (node 7.x and above).
Reference preservation
swagger2openapi preserves $ref
JSON references in your API definition, and does not dereference
every item, as with some model-based parsers.
Schema transformations
Swagger2openapi will automatically 'repair' a number of problems where non-compliant Swagger 2.0 schemas have been used. It will attempt to transform JSON schemas (used incorrectly) into OpenAPI 3.0.x Schema objects.
Specification extensions
swagger2openapi has support for a limited number of real-world specification extensions which have a direct bearing on the conversion. All other specification extensions are left untouched. swagger2openapi is swaggerplusplus-compatible.
It is expected to be able to configure the process of specification-extension modification using options or a plugin mechanism in a future release.
Tests
To run a test-suite:
node testRunner [-f {path-to-expected-failures}]... [{path-to-APIs|single-file...}]
The test harness currently expects files with a .json
or .yaml
extension, or a single named file, and has been tested on Node.js versions 4.x, 6.x and 8.7 (it is not recommended to run the test suite under Node.js version 7.x or Node.js versions less than 8.7.0 because of this bug) against
Additionally swagger2openapi has been tested on a corpus of 34,679 real-world valid Swagger 2.0 definitions from GitHub and SwaggerHub. However, if you have a definition which causes errors in the converter or does not pass validation, please do not hesitate to raise an issue.
License
BSD-3-Clause except the openapi-3.0.json
schema, which is taken from the OpenAPI-Specification and the alternative gnostic-3.0.json
schema, which is originally from Google Gnostic. Both of these are licensed under the Apache-2 license.