Package Exports

swagger2openapi
swagger2openapi/package.json

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (swagger2openapi) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

swagger2openapi

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

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        write YAML, default JSON (overridden by --outfile filepath extension)   [boolean]

or use the APIs:

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

var validator = require('swagger2openapi/validate.js');
var options = {};
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 complete documentation of the options object.

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

Browser Support

See initial documentation.

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

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

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

License

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.