Research
Security News
Threat Actor Exposes Playbook for Exploiting npm to Build Blockchain-Powered Botnets
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
swagger2openapi
Advanced tools
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.json
Swagger 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.
Convert Swagger 2.0 definitions into OpenApi 3.0.x
Currently tracking v3.0.0-RC0
Usage:
Options:
-d, --debug enable debug mode, adds specification-extensions [boolean]
-h, --help Show help [boolean]
-o, --outfile the output file to write to [string]
-y, --yaml read and write YAML, default JSON [boolean]
or use the APIs:
var converter = require('swagger2openapi');
var options = {};
//options.debug = true; // sets various x-s2o- debugging properties
var openapi = converter.convert(swagger, options);
var validator = require('swagger2openapi/validate.js');
var options = {};
var result = validator.validate(openapi, options);
Or use the online version which also includes an API
swagger2openapi has support for a limited number of real-world vendor extensions which have a direct bearing on the conversion. All other vendor extensions are left untouched.
Vendor Extension | Vendor | Conversion Performed |
---|---|---|
x-ms-paths | Microsoft | Treated as an analogue of the openapi.paths object |
x-ms-skip-url-encoding | Microsoft | For query parameters, converted to allowReserved:true |
x-ms-odata | Microsoft | References to #/definitions/ are updated to #/components/schemas |
x-ms-parameterized-host | Microsoft | TODO Not seen in the wild |
x-anyOf | Open Nitro Project | Within schemas, converted to anyOf |
x-oneOf | Open Nitro Project | Within schemas, converted to oneOf |
x-not | Open Nitro Project | Within schemas, converted to not |
See also Amazon API Gateway vendor extensions
It is expected to be able to configure the process of vendor-extension modification using options or a plugin mechanism in a future release.
To run a test-suite:
node testRunner {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 and 6.x against
It can also be used as a simple validator if given an existing OpenAPI 3.x definition
Also included is a tool reportExtensions
to gather a list of vendor (specification) extensions and formats used in a definition or corpus of definitions. For examples of output, see the wiki
FAQs
Convert Swagger 2.0 definitions to OpenApi 3.0 and validate
The npm package swagger2openapi receives a total of 1,149,690 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.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.