swagger2openapi

Convert Swagger 2.0 definitions into OpenApi 3.0.x

Currently trackingv3.0.0

If you are using Node.js 4 - please use the --harmony flag

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:

varconverter=require('swagger2openapi');
varoptions={};
//options.patch = true; // fix up small errors in the source definition
//options.warnOnly = true; // Do not throw on non-patchable errors
converter.convertObj(swagger,options,function(err,options){
// options.openapi contains the converted definition
});
// also available are asynchronous convertFile, convertUrl, convertStr and convertStream functions
// if you omit the callback parameter, you will instead receive a Promise

varvalidator=require('swagger2openapi/validate.js');
varoptions={};
validator.validate(openapi,options,function(err,options){
// options.valid contains the result of the validation
// options.context now contains a stack (array) of JSON-Pointer strings
});
// also available is a synchronous validateSync method which returns a boolean

See here for completedocumentationof theoptionsobject.

Or use theonline versionwhich also includes its ownAPI.

Browser Support

Seeinitial documentation.

Features

OpenAPI 3.0.x validation

ThetestRunnerharness can also be used as a simple validator if given one or more existing OpenAPI 3.x definitions. The validator (however it is called) usesWHATWGURL parsing if available (node 7.x and above). The testRunner can have a linting mode enabled with the--lintoption. Rules are definedhere.Contributions of rules and rule actions for the linter are very much appreciated.

Reference preservation

swagger2openapi preserves$refJSON 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-worldspecification extensionswhich have a direct bearing on the conversion. All other specification extensions are left untouched. swagger2openapi isswaggerplusplus-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.jsonor.yamlextension, or a single named file, and has been tested on Node.js versions 4.x, 6.x and 8.x LTS (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 ofthis bug) against

• APIs.guru
• Mermade OpenApi specifications collection
• OpenAPI3-Examples (pass/fail)
• SOM-Research collection

Additionally swagger2openapi has been tested on a corpus of 34,679 real-world valid Swagger 2.0 definitions from GitHub andSwaggerHub.However, if you have a definition which causes errors in the converter or does not pass validation, please do not hesitate toraise an issue.

License

BSD-3-Clauseexcept theopenapi-3.0.jsonschema, which is taken from theOpenAPI-Specificationand the alternativegnostic-3.0.jsonschema, which is originally fromGoogle Gnostic.Both of these are licensed under theApache-2license.