API Specification Converter

Common errors

Warnings

Install

Imports

• Converter
  wrong

  import { Converter } from 'api-spec-converter';

  correct

  const Converter = require('api-spec-converter');

  The library primarily exposes its main conversion functionality as a default CommonJS export. While Node.js ESM interop may allow `import Converter from 'api-spec-converter';`, the `require()` syntax is explicitly documented and guarantees correct behavior.

• APISpecConverter
  wrong

  const APISpecConverter = require('api-spec-converter').APISpecConverter;

  correct

  APISpecConverter.convert(...); // after <script src="..."></script>

  This symbol is a global variable made available only when the UMD build (`dist/api-spec-converter.js`) is loaded directly in a browser environment via a `<script>` tag. It is not available as a named export from the Node.js package.

• Converter (ESM)
  wrong

  import { convert } from 'api-spec-converter';

  correct

  import Converter from 'api-spec-converter';

  For modern Node.js ESM projects, the CommonJS default export is typically consumed as a default import. There are no named exports like `convert` directly from the package root.

Quickstart

This example demonstrates how to programmatically convert an OpenAPI 1.x (Swagger 1.x) specification from a URL to OpenAPI 2.0, fill in any missing required fields with dummy data, validate the resulting specification, and then write it to a local JSON file.

const Converter = require('api-spec-converter');
const fs = require('fs');

Converter.convert({
  from: 'swagger_1',
  to: 'swagger_2',
  source: 'https://raw.githubusercontent.com/LucyBot-Inc/api-spec-converter/master/test/input/swagger_1/petstore/pet.json',
})
  .then(function(converted) {
    // Optionally fill missing required fields with dummy data
    converted.fillMissing();

    // Validate the converted specification
    return converted.validate()
      .then(function (result) {
        if (result.errors && result.errors.length > 0)
          return console.error('Validation Errors:', JSON.stringify(result.errors, null, 2));
        if (result.warnings && result.warnings.length > 0)
          console.warn('Validation Warnings:', JSON.stringify(result.warnings, null, 2));

        // Save the converted spec to a file
        fs.writeFileSync('converted-swagger2.json', converted.stringify({ syntax: 'json', order: 'openapi' }));
        console.log('Converted spec saved to converted-swagger2.json');
      })
      .catch(function(validationErr) {
          console.error('Validation failed:', validationErr);
      });
  })
  .catch(function(conversionErr) {
    console.error('Conversion failed:', conversionErr);
  });