CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-apidevtools--swagger-parser

Swagger 2.0 and OpenAPI 3.0 parser and validator for Node and browsers

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Swagger Parser

Swagger Parser is a comprehensive library for parsing, validating, resolving, and dereferencing Swagger 2.0 and OpenAPI 3.0/3.1 specifications. It provides both callback and Promise/async-await interfaces, with full support for JSON references ($ref pointers), circular references, and both Node.js and browser environments.

Package Information

  • Package Name: @apidevtools/swagger-parser
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @apidevtools/swagger-parser

Core Imports

import SwaggerParser from "@apidevtools/swagger-parser";
// or
import { validate } from "@apidevtools/swagger-parser";

For CommonJS:

const SwaggerParser = require("@apidevtools/swagger-parser");
// or
const { validate } = require("@apidevtools/swagger-parser");

Basic Usage

import SwaggerParser from "@apidevtools/swagger-parser";

// Validate an API specification
try {
  const api = await SwaggerParser.validate("./api-spec.yaml");
  console.log("API name: %s, Version: %s", api.info.title, api.info.version);
} catch (err) {
  console.error("Validation failed:", err);
}

// Parse and dereference all $ref pointers
const api = await SwaggerParser.dereference("./api-spec.yaml");
// Now api is a plain JavaScript object with no $ref pointers

// Bundle multiple files into a single specification
const bundled = await SwaggerParser.bundle("./api-spec.yaml");
// Contains only internal $ref pointers, safe for JSON.stringify()

Architecture

Swagger Parser is built on several key components:

  • SwaggerParser Class: Main class extending $RefParser with OpenAPI-specific validation
  • Static Methods: Convenience methods for one-off operations without creating instances
  • Validation System: Two-tier validation (JSON schema + specification rules)
  • Reference Resolution: Handles $ref pointers, including external files and circular references
  • Options System: Configurable parsing, validation, and resolution behavior
  • Multi-format Support: Works with JSON, YAML, and mixed format specifications

Capabilities

API Parsing

Basic parsing functionality that reads OpenAPI/Swagger files and converts them to JavaScript objects, with format validation and version checking.

function parse(
  api: string | OpenAPI.Document,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;
function parse(
  api: string | OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;
function parse(
  baseUrl: string,
  api: string | OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;

API Parsing

API Validation

Comprehensive validation system that parses, dereferences, and validates OpenAPI specifications against both JSON schemas and specification rules.

function validate(
  api: string | OpenAPI.Document,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;
function validate(
  api: string | OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;
function validate(
  baseUrl: string,
  api: string | OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;

API Validation

Reference Resolution

Resolves all JSON references ($ref pointers) in OpenAPI specifications, downloading external files and providing a map of all resolved references.

function resolve(
  api: string | OpenAPI.Document,
  callback?: SwaggerParser.$RefsCallback
): Promise<$Refs>;
function resolve(
  api: string | OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.$RefsCallback
): Promise<$Refs>;
function resolve(
  baseUrl: string,
  api: string | OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.$RefsCallback
): Promise<$Refs>;

Reference Resolution

API Bundling

Bundles multiple OpenAPI files into a single specification with only internal $ref pointers, eliminating external dependencies while preserving references.

function bundle(
  api: string | OpenAPI.Document,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;
function bundle(
  api: string | OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;
function bundle(
  baseUrl: string,
  api: string | OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;

API Bundling

API Dereferencing

Replaces all $ref pointers with their resolved values, creating a plain JavaScript object tree with maintained object reference equality.

function dereference(
  api: string | OpenAPI.Document,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;
function dereference(
  api: string | OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;
function dereference(
  baseUrl: string,
  api: string | OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;

API Dereferencing

Types

declare class SwaggerParser {
  /** The parsed/bundled/dereferenced OpenAPI definition */
  public api: OpenAPI.Document;
  
  /** Map of all externally-referenced files and JSON pointers */
  public $refs: $Refs;
  
  // Instance methods have same overloads as static methods
  public parse(api: string | OpenAPI.Document, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  public parse(api: string | OpenAPI.Document, options?: SwaggerParser.Options, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  public parse(baseUrl: string, api: string | OpenAPI.Document, options?: SwaggerParser.Options, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  
  public validate(api: string | OpenAPI.Document, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  public validate(api: string | OpenAPI.Document, options?: SwaggerParser.Options, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  public validate(baseUrl: string, api: string | OpenAPI.Document, options?: SwaggerParser.Options, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  
  public resolve(api: string | OpenAPI.Document, callback?: SwaggerParser.$RefsCallback): Promise<$Refs>;
  public resolve(api: string | OpenAPI.Document, options?: SwaggerParser.Options, callback?: SwaggerParser.$RefsCallback): Promise<$Refs>;
  public resolve(baseUrl: string, api: string | OpenAPI.Document, options?: SwaggerParser.Options, callback?: SwaggerParser.$RefsCallback): Promise<$Refs>;
  
  public bundle(api: string | OpenAPI.Document, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  public bundle(api: string | OpenAPI.Document, options?: SwaggerParser.Options, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  public bundle(baseUrl: string, api: string | OpenAPI.Document, options?: SwaggerParser.Options, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  
  public dereference(api: string | OpenAPI.Document, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  public dereference(api: string | OpenAPI.Document, options?: SwaggerParser.Options, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
  public dereference(baseUrl: string, api: string | OpenAPI.Document, options?: SwaggerParser.Options, callback?: SwaggerParser.ApiCallback): Promise<OpenAPI.Document>;
}

namespace SwaggerParser {
  export type ApiCallback = (err: Error | null, api?: OpenAPI.Document) => any;
  export type $RefsCallback = (err: Error | null, $refs?: $Refs) => any;
  
  export interface Options extends Partial<ParserOptions> {
    validate?: {
      /** Enable/disable JSON schema validation */
      schema?: boolean;
      /** Enable/disable Swagger spec validation */
      spec?: boolean;
    };
  }
}

docs

bundling.md

dereferencing.md

index.md

parsing.md

resolution.md

validation.md

tile.json