swagger2openapi
Advanced tools
Package description
The swagger2openapi npm package is designed to convert Swagger 2.0 definitions into OpenAPI 3.0.x, facilitating the transition to the newer OpenAPI specification. It supports both command-line and programmatic usage, making it a versatile tool for developers working with API documentation and specifications.
Conversion of Swagger 2.0 to OpenAPI 3.0
This feature allows users to programmatically convert Swagger 2.0 API definitions to OpenAPI 3.0 specifications. The code sample demonstrates how to load a Swagger 2.0 JSON file, convert it, and then log the resulting OpenAPI 3.0 specification.
const converter = require('swagger2openapi');
const swagger = require('./swagger.json');
converter.convertObj(swagger, {}, (err, options) => {
if (err) {
console.error(err);
} else {
console.log(options.openapi);
}
});Validation of converted OpenAPI 3.0 definitions
Beyond conversion, the package also offers validation of the resulting OpenAPI 3.0 definitions. This ensures that the conversion process not only translates the specification but also checks for any inconsistencies or errors in the new format.
const converter = require('swagger2openapi');
const swagger = require('./swagger.json');
converter.convertObj(swagger, {validate: true}, (err, options) => {
if (err) {
console.error('Validation error:', err);
} else {
console.log('Validation successful. OpenAPI 3.0 output:', options.openapi);
}
});Command-line conversion
For users preferring command-line tools, swagger2openapi provides a straightforward way to convert Swagger 2.0 files to OpenAPI 3.0 by specifying the input and output files directly in the terminal.
swagger2openapi swagger.json -o openapi.jsonSwagger Parser is a package that can validate and dereference Swagger files. While it primarily focuses on Swagger 2.0, it also supports OpenAPI 3.0 to some extent. Compared to swagger2openapi, Swagger Parser offers validation and dereferencing but not direct conversion between the two specifications.
openapi3-ts provides TypeScript definitions for OpenAPI 3.0. While it doesn't offer conversion capabilities, it's a useful tool for developers working with OpenAPI 3.0 in TypeScript projects, complementing swagger2openapi by providing type checking and autocompletion.
Readme
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 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.
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]
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.
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.
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 (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.
FAQs
Convert Swagger 2.0 definitions to OpenApi 3.0 and validate
The npm package swagger2openapi receives a total of 1,001,578 weekly downloads. As such, swagger2openapi popularity was classified as popular.
We found that swagger2openapi demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.
Security News
A JavaScript library maintainer is under fire after merging a controversial PR to support legacy versions of Node.js.
Security News
Results from the 2023 State of JavaScript Survey highlight key trends, including Vite's dominance, rising TypeScript adoption, and the enduring popularity of React. Discover more insights on developer preferences and technology usage.