swagger2openapi
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.
Currently tracking v3.0.x
Installation:
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 filepath extension) [boolean] -b, --rbname Extension to use to preserve body parameter names in converted operations ("" == disabled) [string] [default: ""]
B. Node.js API:
const converter = ;let options = {};//options.patch = true; // fix up small errors in the source definition//options.warnOnly = true; // Do not throw on non-patchable errorsconverter;// 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.
C. Browser:
Or use the online version which also includes its own API.
Browser Support
Features
OpenAPI 3.0.x validation
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 $ref
s 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.
Tests
To run a test-suite:
node oas-validate [-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 LTS Node.js versions against
- APIs.guru
- Mermade OpenApi specifications collection
- OpenAPI3-Examples (pass/fail)
- SOM-Research collection
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.
Version history
License
BSD-3-Clause except the openapi-3.0.json
schema, which is taken from the OpenAPI-Specification which is licensed under the Apache-2 license.