{"id":15961,"library":"api-spec-converter","title":"API Specification Converter","description":"The `api-spec-converter` package provides a utility for transforming API descriptions between various popular formats, including OpenAPI (formerly Swagger), RAML, API Blueprint, I/O Docs, Google Discovery, and WADL. As of its current stable version, 2.12.0, its core functionality is robust for conversions *to* OpenAPI 2.0 and *from* OpenAPI 2.0 to OpenAPI 3.x. This specialized focus means it does not offer full bidirectional conversion support for all listed formats. The library offers both a command-line interface (CLI) for quick conversions and a programmatic API for Node.js and browser environments, supporting both traditional callback and modern Promise-based asynchronous patterns. While a specific release cadence isn't explicitly stated, the version numbering indicates ongoing development and maintenance, making it a reliable choice for its specific conversion strengths within the API ecosystem.","status":"active","version":"2.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/lucybot/api-spec-converter","tags":["javascript","API","REST","Restful","convert","converter","OpenAPI","OpenAPI Specification","Swagger"],"install":[{"cmd":"npm install api-spec-converter","lang":"bash","label":"npm"},{"cmd":"yarn add api-spec-converter","lang":"bash","label":"yarn"},{"cmd":"pnpm add api-spec-converter","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { Converter } from 'api-spec-converter';","symbol":"Converter","correct":"const Converter = require('api-spec-converter');"},{"note":"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.","wrong":"const APISpecConverter = require('api-spec-converter').APISpecConverter;","symbol":"APISpecConverter","correct":"APISpecConverter.convert(...); // after <script src=\"...\"></script>"},{"note":"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.","wrong":"import { convert } from 'api-spec-converter';","symbol":"Converter (ESM)","correct":"import Converter from 'api-spec-converter';"}],"quickstart":{"code":"const Converter = require('api-spec-converter');\nconst fs = require('fs');\n\nConverter.convert({\n  from: 'swagger_1',\n  to: 'swagger_2',\n  source: 'https://raw.githubusercontent.com/LucyBot-Inc/api-spec-converter/master/test/input/swagger_1/petstore/pet.json',\n})\n  .then(function(converted) {\n    // Optionally fill missing required fields with dummy data\n    converted.fillMissing();\n\n    // Validate the converted specification\n    return converted.validate()\n      .then(function (result) {\n        if (result.errors && result.errors.length > 0)\n          return console.error('Validation Errors:', JSON.stringify(result.errors, null, 2));\n        if (result.warnings && result.warnings.length > 0)\n          console.warn('Validation Warnings:', JSON.stringify(result.warnings, null, 2));\n\n        // Save the converted spec to a file\n        fs.writeFileSync('converted-swagger2.json', converted.stringify({ syntax: 'json', order: 'openapi' }));\n        console.log('Converted spec saved to converted-swagger2.json');\n      })\n      .catch(function(validationErr) {\n          console.error('Validation failed:', validationErr);\n      });\n  })\n  .catch(function(conversionErr) {\n    console.error('Conversion failed:', conversionErr);\n  });","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<6.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For ES Modules, use `import Converter from 'api-spec-converter';`. For CommonJS, use `const Converter = require('api-spec-converter');`.","cause":"Attempting to import `Converter` as a named export (`import { Converter } from 'api-spec-converter';`) when it is exposed as a default CommonJS export.","error":"TypeError: Converter.convert is not a function"},{"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.","cause":"Trying to use the `APISpecConverter` global variable in a Node.js environment without properly importing the module.","error":"ReferenceError: APISpecConverter is not defined"},{"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.","cause":"Providing an unrecognized or unsupported API specification format string to the `from` or `to` options during conversion.","error":"Error: Unknown format 'unsupported_format'"}],"ecosystem":"npm"}