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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SwaggerParser
✓ import SwaggerParser from '@apidevtools/swagger-parser';
✗ import { SwaggerParser } from '@apidevtools/swagger-parser';
The library primarily uses a default export for the main `SwaggerParser` object, which then exposes methods like `validate`, `parse`, `bundle`, and `dereference`.
SwaggerParser (CommonJS)
✓ const SwaggerParser = require('@apidevtools/swagger-parser');
✗ const { SwaggerParser } = require('@apidevtools/swagger-parser');
For CommonJS environments in Node.js, the main object is obtained via a direct `require` assignment, consistent with the default export pattern.
Type Definitions
✓ import type SwaggerParser from '@apidevtools/swagger-parser';
✗ import { SwaggerParser } from '@apidevtools/swagger-parser/types';
TypeScript types are shipped with the package and can be imported using standard type import syntax if needed for specific type-only usage, though usually inferred from the default import.
This quickstart demonstrates how to use `SwaggerParser.validate` to check an OpenAPI specification for correctness, followed by optional `bundle` and `dereference` operations. It uses an in-memory OpenAPI object, but a file path or URL could also be provided.
import SwaggerParser from '@apidevtools/swagger-parser';
const myOpenApiSpec = {
openapi: '3.0.0',
info: {
title: 'Example API',
version: '1.0.0',
description: 'A simple example OpenAPI specification'
},
paths: {
'/hello': {
get: {
summary: 'Say hello',
responses: {
'200': {
description: 'A greeting message',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
message: { type: 'string' }
}
}
}
}
}
}
}
}
},
components: {
schemas: {
User: {
type: 'object',
properties: {
id: { type: 'integer', format: 'int64' },
name: { type: 'string' }
}
}
}
}
};
async function validateAndLog() {
try {
// Validate the API spec. This can be a local file path, URL, or JavaScript object.
let api = await SwaggerParser.validate(myOpenApiSpec);
console.log("API name: %s, Version: %s", api.info.title, api.info.version);
console.log("API validation successful!");
// Optionally, bundle all external references into a single document
let bundledApi = await SwaggerParser.bundle(myOpenApiSpec);
// console.log('Bundled API:', JSON.stringify(bundledApi, null, 2));
// Optionally, dereference all pointers to get a plain JavaScript object
let dereferencedApi = await SwaggerParser.dereference(myOpenApiSpec);
// console.log('Dereferenced API:', JSON.stringify(dereferencedApi, null, 2));
} catch (err) {
console.error("Error validating/processing API:", err.message);
if (err.details) {
console.error("Details:", err.details);
}
}
}
validateAndLog();
Debug
Known issues
breakingStarting with version 12.0.0, the default HTTP resolver no longer allows requests to internal URLs due to security concerns. This was implemented to prevent potential vulnerabilities related to internal URL resolution. If you relied on this behavior, your applications might break.fixIf your use case legitimately requires resolving internal URLs via the HTTP resolver, you must explicitly enable the `safeUrlResolver` flag in your HTTP resolver configuration. Review your specifications and ensure no malicious internal URLs can be accessed.
affects: >=12.0.0
gotchaOlder versions of this library were published directly under `swagger-parser` without the `@apidevtools` scope. If you are migrating from an older project or encountering issues with missing modules, ensure you are installing and importing `@apidevtools/swagger-parser`.fixUpdate your `package.json` dependency to `"@apidevtools/swagger-parser": "^12.0.0"` (or your desired version) and adjust import statements accordingly to `import SwaggerParser from '@apidevtools/swagger-parser';` or `const SwaggerParser = require('@apidevtools/swagger-parser');`. affects: <10.0.0 (historical)
gotchaWhen parsing OpenAPI specifications, ensure your `swagger-parser` version supports the exact OpenAPI version you are using. New OpenAPI specification versions introduce new features and structural changes that older parsers might not recognize, leading to validation errors.fixAlways refer to the `swagger-parser` changelog and documentation to confirm support for specific OpenAPI versions (e.g., v12.1.0 supports OpenAPI 3.1.2). Upgrade `swagger-parser` to the latest stable version if you are working with newer OpenAPI specifications.
affects: All versions
Errors
Common errors & fixes
Error: EHOSTUNREACH: host unreachable, 'http://localhost/internal-spec.yaml'
Attempting to resolve a local or internal URL via the HTTP resolver when the `safeUrlResolver` flag is not enabled, following the breaking change in v12.0.0.
fixFor v12.0.0 and above, if you need to resolve internal HTTP/S URLs, configure your `http` resolver with `safeUrlResolver: true`. For local files, ensure you are using a file path and not a `localhost` URL if not running a local server.
Error: Cannot find module 'swagger-parser'
The package name has been updated to be scoped under `@apidevtools`. Projects attempting to `require` or `import` the old unscoped package name will fail.
fixChange your dependency in `package.json` from `swagger-parser` to `@apidevtools/swagger-parser` and update all `require()` or `import` statements accordingly.
Audit
Dependencies
No dependency data recorded yet.