npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@aleung/swagger2openapi

v5.3.2

Published

Convert Swagger 2.0 definitions to OpenApi 3.0 and validate

Downloads

8

Readme

swagger2openapi

logo

OpenAPI Validation Build Tested on APIs.guru 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.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 = 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.

C. Browser:

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

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 8.x and 10.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 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.