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:

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 API:

var options = {};
//options.debug = true; // sets various x-s2o- properties for debugging
var openapi = converter.convert(swagger, options);

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