Registry / serialization / api-spec-converter

api-spec-converter

JSON →
library2.12.0jsnpmunverified

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.

serializationhttp-networking
npm install api-spec-converter
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · API-SPEC-CONVERTER
A
api-spec-converter
serializationjavascriptv2.12.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Converter
✓ const Converter = require('api-spec-converter');
✗ import { Converter } from '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
✓ APISpecConverter.convert(...); // after <script src="..."></script>
✗ const APISpecConverter = require('api-spec-converter').APISpecConverter;
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)
✓ import Converter from 'api-spec-converter';
✗ import { convert } 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.

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); });
api-spec-converter --version
Debug
Known issues
breakingThe 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.
affects: >=2.0.0
gotchaUsers 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`.
affects: >=1.0.0
gotchaThis 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.
affects: <6.0.0
Errors
Common errors & fixes
TypeError: Converter.convert is not a function
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
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'
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.
Upgrade
Version history
2.12.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
1
Resources
githubhttps://github.com/lucybot/api-spec-converter ↗
packagehttps://www.npmjs.com/package/api-spec-converter ↗
homepagehttps://lucybot.com ↗
api-spec-converter — npm install api-spec-converter · libregistry