API Specification Converter

Common errors

• TypeError: Converter.convert is not a function

  cause Attempting to import `Converter` as a named export (`import { Converter } from 'api-spec-converter';`) when it is exposed as a default CommonJS export.
  fix For ES Modules, use `import Converter from 'api-spec-converter';`. For CommonJS, use `const Converter = require('api-spec-converter');`.

• ReferenceError: APISpecConverter is not defined

  cause Trying to use the `APISpecConverter` global variable in a Node.js environment without properly importing the module.
  fix In Node.js, you must `require()` or `import` the module using `const Converter = require('api-spec-converter');`. The `APISpecConverter` global is only available in browsers after including the UMD build script.

• Error: Unknown format 'unsupported_format'

  cause Providing an unrecognized or unsupported API specification format string to the `from` or `to` options during conversion.
  fix Ensure the format strings match the officially supported list: `swagger_1`, `swagger_2`, `openapi_3`, `api_blueprint`, `io_docs`, `google`, `raml`, `wadl`. Also, verify the conversion path (e.g., from `raml` to `openapi_3`) is supported.

Warnings

• breaking The library has significant limitations on the types of conversions it supports. It primarily supports converting *to* OpenAPI (fka Swagger) 2.0 and *from* OpenAPI 2.0 to OpenAPI 3.x. Full bidirectional conversion between all listed formats (RAML, API Blueprint, WADL, etc.) is not supported, and attempting conversions outside the documented paths will fail.
  Fix: Always verify the 'from' and 'to' formats against the officially supported conversion paths in the README before attempting conversion. If you need broader or more complex inter-format conversions, consider using other tools or manual migration.
• gotcha Users installing the global CLI tool (`npm install -g api-spec-converter`) may encounter issues, particularly on Windows or with certain Node.js/NPM configurations. A known issue (GitHub issue #132) highlights potential problems during global installation.
  Fix: If global installation fails, try `npm install --force -g api-spec-converter` or use `npm install api-spec-converter` for local project-level usage and run it via `npx api-spec-converter`.
• gotcha This package requires Node.js version 6.0.0 or higher. Running it with older Node.js versions may lead to unexpected errors or silent failures due to incompatible syntax or missing APIs.
  Fix: Ensure your Node.js environment meets or exceeds version 6.0.0. Use a Node.js version manager like `nvm` or `fnm` to easily switch and manage Node.js versions.

Install

• npm install api-spec-converter npm
• yarn add api-spec-converter yarn
• pnpm add api-spec-converter pnpm

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);
  });