swagger2openapi

!logo

!Build

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:
``bash
npm install -g swagger2openapi
`
Or, add it to your node.js projects as shown below in option B.

Usage:

$3

`text
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: ""]
`

$3

`javascript
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 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
`

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.

$3

Or use the online version which also includes its own API.

#### Browser Support

See initial documentation.

Features

$3

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.

`text
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]
`

$3

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.

$3

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.

$3

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:

`shell
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.

$3

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.

$3

* Change-Log

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.