@apidevtools/swagger-parser

Swagger Parser reads Swagger 2.0 and OpenAPI 3.0/3.1 API definitions in JSON or YAML, validates them against the official schemas, and resolves every $ref pointer — including ones that point to external files or URLs — into a single, easy-to-use JavaScript object. It builds on @apidevtools/json-schema-ref-parser for the underlying reference-resolution engine and layers Swagger/OpenAPI-specific schema and semantic validation on top.

Beyond simple parsing, it can bundle a multi-file API definition into one file with only internal references, or fully dereference it into a plain object with no $ref pointers at all, while preserving object identity so that multiple references to the same definition resolve to the same instance. It’s tested against the Swagger 2.0 and OpenAPI 3.0 JSON Schemas as well as over 1,500 real-world API definitions from major providers, and runs in both Node.js and modern browsers.

What You Get

• Parsing of Swagger/OpenAPI specs from JSON or YAML, from a file path, URL, or in-memory object
• Schema validation against the official Swagger 2.0 and OpenAPI 3.0/3.1 JSON Schemas, plus additional semantic checks
• resolve() to resolve every $ref pointer including external files and URLs, bundle() to collapse a multi-file spec into one file with only internal refs, and dereference() to produce a plain object with no $refs at all
• Support for circular references, nested references, and back-references, with object-identity preservation so identical $ref targets resolve to the same instance
• Works identically in Node.js and modern web browsers, with both CommonJS and ESM import styles

Common Use Cases

• Validating an OpenAPI/Swagger definition file in CI before publishing it or generating client/server code from it
• Loading a multi-file API spec (with external $refs split across files) and bundling or fully dereferencing it into one self-contained object for downstream tooling
• Building developer tools (mock servers, documentation generators, code generators) that need a fully resolved, validated in-memory representation of an API definition
• Programmatically inspecting or transforming an API definition’s structure, e.g. checking api.info.version after parsing before running further processing

Under The Hood

Architecture: SwaggerParser (lib/index.js) subclasses $RefParser from the sibling @apidevtools/json-schema-ref-parser package, so parse, resolve, bundle, and dereference all defer to that package’s reference-resolution engine, with this package layering Swagger/OpenAPI-specific behavior on top: after super.parse() returns a raw JS object, it checks version fields (schema.swagger / schema.openapi) against supportedVersions (3.0.x/3.1.x plus legacy 2.0) and raises helpful SyntaxErrors for common mistakes like a numeric version field. Validation itself is split across lib/validators/schema.js (JSON Schema conformance) and lib/validators/spec.js (Swagger/OpenAPI-specific semantic rules beyond what a JSON Schema can express), with lib/options.js centralizing configurable parser behavior.

Tech Stack: Plain JavaScript (no build/transpile step for the library itself, lib/index.d.ts ships hand-written TypeScript typings), with @apidevtools/json-schema-ref-parser, @apidevtools/openapi-schemas, and @apidevtools/swagger-methods as first-party dependencies from the same APIDevTools org, plus ajv/ajv-draft-04 for JSON Schema validation and call-me-maybe to support both promise and Node-style-callback call conventions. Test tooling uses Mocha, Chai, nyc for coverage, and a TypeScript compile-check of the .d.ts file against real usage.

Code Quality: The test/specs directory is unusually thorough for a small library — dedicated suites for circular references, deep-circular references, callback-vs-promise APIs, invalid specs, relative OAS servers, and a curated ‘real-world’ folder of specs from actual providers, plus a TypeScript-definition test that type-checks the .d.ts file against sample usage. Error handling favors specific, actionable messages (e.g. distinguishing a stringly-typed vs numeric version field) rather than generic failures. Repo health scoring flags low recent commit activity/infrequent maintenance, consistent with a mature, largely-feature-complete library that doesn’t need frequent changes.

API Design: The four core verbs — parse, resolve, bundle, dereference — map directly onto the four things a consumer actually wants to do with a multi-file spec, and each is available in both callback and promise/async-await form via the call-me-maybe shim, so callers can adopt whichever style their codebase already uses. Subclassing the underlying ref-parser rather than wrapping it means advanced users can drop to the lower-level $RefParser API when they need generic JSON Schema ref-resolution behavior not specific to Swagger/OpenAPI.