Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


3.2.8 • Public • Published



OpenAPI Validation Build Tested on Tested on Mermade OpenAPIs Coverage Status Known Vulnerabilities Greenkeeper badge

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.0


swagger2openapi [options] [filename|url]
  --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
  -y, --yaml        write YAML, default JSON (overridden by --outfile filepath extension)   [boolean]

or use the API:

var converter = require('swagger2openapi');
var 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

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.


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-specs}...
  --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 specs 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 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.

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.


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 Node.js versions 4.x, 6.x and 8.x LTS (it is not recommended to run the test suite under Node.js versions >=7.0.0 and <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.

Regression tests

Regression tests (thanks @domharrington) live in the /test directory and can be run with npx mocha. Each sub-directory 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.


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.


npm i swagger2openapi

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability