# swagger2openapi > Convert Swagger 2.0 definitions to OpenApi 3.0 and validate Latest version **7.0.8** (published 2021-07-07) · BSD-3-Clause license · 0 weekly downloads ## Install ```sh npm install swagger2openapi pnpm add swagger2openapi yarn add swagger2openapi bun add swagger2openapi ``` Provides the commands `boast`, `oas-validate`, `swagger2openapi`. ## Health **Score 23/100 (F)** — status: abandoned. Positive: has types package; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 7.0.8 | | Published | 2021-07-07 | | First published | 2016-12-19 | | Weekly downloads | 0 | | License | BSD-3-Clause | | TypeScript types | separate (@types/swagger2openapi) | | Module format | CommonJS | | Dependencies | 11 | | Unpacked size | 102.2 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 747 | | Author | Mike Ralphson | | Maintainers | mermade | | Keywords | swagger, openapi, openapi2, openapi3, converter, conversion, validator, validation, resolver, lint, linter | ## Links - npm: https://www.npmjs.com/package/swagger2openapi - Repository: https://github.com/Mermade/oas-kit - Homepage: https://github.com/Mermade/oas-kit#readme - Issues: https://github.com/mermade/oas-kit/issues - Funding: https://github.com/Mermade/oas-kit?sponsor=1 - npm.io page: https://npm.io/package/swagger2openapi ## Dependencies (11) - [yaml](https://npm.io/package/yaml.md) ^1.10.0 - [yargs](https://npm.io/package/yargs.md) ^17.0.1 - [reftools](https://npm.io/package/reftools.md) ^1.1.9 - [node-fetch](https://npm.io/package/node-fetch.md) ^2.6.1 - [oas-resolver](https://npm.io/package/oas-resolver.md) ^2.5.6 - [call-me-maybe](https://npm.io/package/call-me-maybe.md) ^1.0.1 - [node-fetch-h2](https://npm.io/package/node-fetch-h2.md) ^2.3.0 - [oas-validator](https://npm.io/package/oas-validator.md) ^5.0.8 - [node-readfiles](https://npm.io/package/node-readfiles.md) ^0.2.0 - [oas-kit-common](https://npm.io/package/oas-kit-common.md) ^1.0.8 - [oas-schema-walker](https://npm.io/package/oas-schema-walker.md) ^1.1.5 ## Alternatives - [eslint-plugin-sonarjs](https://npm.io/package/eslint-plugin-sonarjs.md) — 2.9M weekly downloads - [eslint-config-expo](https://npm.io/package/eslint-config-expo.md) — 1.5M weekly downloads - [@matter/protocol](https://npm.io/package/@matter/protocol.md) — 63.5K weekly downloads - [@eventcatalog/linter](https://npm.io/package/@eventcatalog/linter.md) — 24.8K weekly downloads - [@inrupt/eslint-config-base](https://npm.io/package/@inrupt/eslint-config-base.md) — 4.5K weekly downloads ## Recent versions - 7.0.8 (latest) — 2021-07-07 - 2.12.0-5 (beta) — 2018-02-07 - 7.0.7 — 2021-06-17 - 7.0.6 — 2021-05-31 - 7.0.5 — 2021-01-24 - 7.0.4 — 2020-11-20 - 7.0.3 — 2020-10-14 - 7.0.2 — 2020-09-22 - 7.0.1 — 2020-09-18 - 7.0.0 — 2020-09-02 - 6.2.3 — 2020-08-12 - 6.2.2 — 2020-07-31 - 6.2.1 — 2020-07-13 - 6.2.0 — 2020-07-13 - 6.1.1 — 2020-07-08 - … 141 more at https://npm.io/package/swagger2openapi/versions ## README # swagger2openapi ![logo](https://github.com/Mermade/oas-kit/blob/master/docs/logo.png?raw=true) [![OpenAPI Validation](https://mermade.org.uk/openapi-converter/api/v1/badge?url=https://mermade.org.uk/openapi-converter/examples/openapi.json)](https://mermade.org.uk/openapi-converter/api/v1/validate?url=https://mermade.org.uk/openapi-converter/examples/openapi.json) ![Build](https://img.shields.io/travis/Mermade/oas-kit/master.svg) [![Tested on APIs.guru](https://api.apis.guru/badges/tested_on.svg)](https://APIs.guru) [![Tested on Mermade OpenAPIs](https://img.shields.io/badge/Additional%20Docs-74426-brightgreen.svg)](https://github.com/mermade/openapi-definitions) [![Coverage Status](https://coveralls.io/repos/github/Mermade/swagger2openapi/badge.svg?branch=master)](https://coveralls.io/github/Mermade/swagger2openapi?branch=master) [![Known Vulnerabilities](https://snyk.io/test/npm/swagger2openapi/badge.svg)](https://snyk.io/test/npm/swagger2openapi) [![Greenkeeper badge](https://badges.greenkeeper.io/Mermade/oas-kit.svg)](https://greenkeeper.io/) Convert Swagger 2.0 definitions into OpenApi 3.0.x The online version of the converter/validator runs on a [Linode](https://www.linode.com/?r=5734be467cc501b23267cf66d451bc339042ddfa) 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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) ## 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: ### A. Command line: ```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: ""] ``` ### B. Node.js API: ```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](/packages/swagger2openapi/boast.js) for a fuller CLI tool for converting, validating and linting. See here for complete [documentation](/docs/options.md) of the `options` object. ### C. Browser: Or use the [online version](https://mermade.org.uk/openapi-converter) which also includes its own [API](http://petstore.swagger.io/?url=https://mermade.org.uk/openapi-converter/contract/swagger.json). #### Browser Support See [initial documentation](/docs/browser.md). ## 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](https://whatwg.org/) 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](/packages/oas-linter/rules.yaml). 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] ``` ### 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](/docs/extensions.md) which have a direct bearing on the conversion. All other specification extensions are left untouched. swagger2openapi is [swaggerplusplus](https://github.com/mermade/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](https://github.com/APIs-guru/openapi-directory) * [Mermade OpenApi specifications collection](https://github.com/mermade/openapi_specifications) * [OpenAPI3-Examples (pass/fail)](https://github.com/mermade/openapi3-examples) * [SOM-Research collection](https://github.com/SOM-Research/hapi) Additionally `swagger2openapi` has been tested on a corpus of 74,426 real-world valid Swagger 2.0 definitions from GitHub and [SwaggerHub](https://swaggerhub.com/). 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](https://github.com/Mermade/swagger2openapi/issues). ### Regression tests Regression tests (thanks [@domharrington](https://github.com/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 * [Change-Log](https://github.com/Mermade/oas-kit/blob/master/CHANGELOG.md#change-log) ## License [BSD-3-Clause](LICENSE) except the `openapi-3.0.json` schema, which is taken from the [OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.yaml) which is licensed under the [Apache-2](http://www.apache.org/licenses/LICENSE-2.0) license. --- _Source: https://npm.io/package/swagger2openapi · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._