swagger2openapi

What is swagger2openapi?

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.

What are swagger2openapi's main functionalities?

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

Other packages similar to swagger2openapi

swagger-parser

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

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

swagger2openapi

Convert Swagger 2.0 definitions into OpenApi 3.0.x

Currently tracking v3.0.0-RC0

Usage:

swagger2openapi [options] [filename|url]
Options:
  -d, --debug    enable debug mode, adds specification-extensions      [boolean]
  -e, --encoding encoding for input/output files      [string] [default: "utf8"]
  -h, --help     Show help                                             [boolean]
  -o, --outfile  the output file to write to                            [string]
  -u, --url      url of original spec, creates x-origin entry           [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.convertSync(swagger, options);
// also available are asynchronous convertObj, convertFile, convertUrl and convertStr functions

var validator = require('swagger2openapi/validate.js');
var options = {};
var result = validator.validate(openapi, options); // returns boolean, throws on error
// options.context now contains a stack (array) of JSON-Pointer strings

Or use the online version which also includes an API

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.

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

Tests

To run a test-suite:

node testRunner [-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 7.x against

• APIs.guru
• Mermade OpenApi specifications collection
• SOM-Research collection (overlaps with APIs.guru)

It can also be used as a simple validator if given an existing OpenAPI 3.x definition. The validator (however it is called) uses WHATWG URL parsing if available (node 7.x and above).

Metadata reporting

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