Convert Swagger 2.0 definitions into OpenApi 3.0.x
The online version of the converter/validator runs on a Linode VPS. If you are considering a hosted server, please sign up through this link so we both receive free credit.
This is a node.js module, which you can run on the command line. First ensure you have npm installed (tested on version 6.1+), and then install as follows:
npm install -g swagger2openapi
Or, add it to your node.js projects as shown below in option B.
Usage:
A. Command line:
swagger2openapi [options] [filename|url]Options: --refSiblings mode to handle $ref's with sibling properties [choices: "remove", "preserve", "allOf"] --resolveInternal resolve internal references also [boolean] --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"] -f, --fatal make resolution errors fatal [boolean] -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] -t, --targetVersion override default target version of 3.0.0 [string] -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 write YAML, default JSON (overridden by --outfile
B. Node.js API:
const converter = require('swagger2openapi');let options = {};//options.patch = true; // fix up small errors in the source definition//options.warnOnly = true; // Do not throw on non-patchable errorsconverter.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
Note that the options object passed in is modified/extended by the convert* functions.
See the boast command-line tool for a fuller CLI tool for converting, validating and linting.
See here for complete documentation of the options object.
oas-validate can be used as a 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). The validator can have a linting mode enabled with the --lint option. Rules are defined here. Contributions of rules and rule actions for the linter are very much appreciated.
oas-validate.js [options] {path-to-docs}...Options: --lint lint the definition [boolean] --validateSchema Run schema validation step: first, last* or never [string] --warnOnly Do not throw on non-patchable errors [boolean] -h, --help Show help [boolean] --version Show version number [boolean] -e, --encoding encoding for input/output files [string] [default: "utf8"] -f, --fail path to docs expected to fail [string] -j, --jsonschema path to alternative JSON schema [string] -l, --laxurls lax checking of empty urls [boolean] -m, --mediatype check media-types against RFC pattern [boolean] -n, --nopatch do not patch minor errors in the source definition [boolean] -o, --output output conversion result [string] [default: "openapi.yaml"] -q, --quiet do not show test passes on console, for CI [boolean] -r, --resolve resolve external references [boolean] -s, --stop stop on first error [boolean] -v, --verbose increase verbosity [count] -w, --whatwg enable WHATWG URL parsing [boolean] -y, --yaml skip YAML-safe test [boolean]
Reference preservation
swagger2openapi by default preserves almost all $ref JSON references in your API definition, and does not dereference
every item, as with some model-based parsers. The exception is internal references within externally referenced documents. To enable internal $ref resolution across the whole document, use the --resolveInternal option, which also disables creation of $refs for shared requestBodies.
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.
Additionally swagger2openapi has been tested on a corpus of 74,426 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.
Regression tests
Regression tests (thanks @domharrington) live in the /test directory and can be run with npx mocha. Each sub-directory of s2o-test should contain an input swagger.yaml file, an expected output openapi.yaml file and an optional options.yaml file. You can put private test cases in sub-directories starting with an underscore character. In the resolver sub-directory, each directory should contain an input.yaml, an output.yaml and an optional options.yaml file.