Swagger Client: resolving and using OpenAPI documents in JavaScript

Reading the OpenAPI compatibility table

The repository's compatibility table maps client versions to specification revisions. The following is a historical excerpt; check the current table and release notes for later versions. It maps client versions to the specification revisions they handle:

| Client | Release date | Spec compatibility | | --- | --- | --- | | 3.37.x | 2026-02-27 | 2.0, 3.0.0 through 3.0.4, 3.1.0, 3.2.0 | | 3.33.x | 2024-12-30 | 2.0, 3.0.0 through 3.0.4, 3.1.0 | | 3.19.x | 2023-01-23 | 2.0, 3.0.0 through 3.0.4, 3.1.0 | | 3.10.x | 2020-01-17 | 2.0, 3.0.0 through 3.0.3 | | 2.1.32 | 2017-01-12 | 1.0, 1.1, 1.2 |

At the time of this review, the main-branch manifest was 3.38.4 while the table did not have a separate 3.38 row. Absence of a row alone does not establish a lack of support: consult release notes and test the specific OpenAPI features you need. The bottom row also points its version at a tree URL for the 2.x line while every other row links a release tag.

Node.js support follows the release calendar, so a minor can drop a runtime

The runtime requirement is Node.js `>=22`, and the library uses the native fetch implementation rather than a polyfill. Node.js 12, 14, 16, 18 and 20 are named as end of life and no longer supported.

The policy behind that line is stated in a note and is unusual enough to quote directly: the minimum Node.js runtime version aligns with the Node.js releases schedule, which is what lets the maintainers drop support for end of life versions without doing a major version bump. In other words the semver promise covers the library's API, not the set of runtimes it will start on. A patch release that raises the floor from one Node major to the next is in scope by that policy.

Browsers are handled on a different schedule and a different mechanism. The supported set is the latest Chrome, Safari, Firefox and Edge, each using its own native fetch. Between them, the two platforms have almost nothing in common except the fetch assumption.

Scarf analytics fire during installation, and two switches turn them off

Installation is observable. The project uses Scarf to collect anonymized installation analytics, states that they help support the maintainers and that they run only during installation, and gives two ways to opt out.

The first is a field in your own manifest:

{
  "scarfSettings": {
    "enabled": false
  }
}

The second is an environment variable applied to whichever npm install runs, given as `SCARF_ANALYTICS=false npm install`. Both are documented, and both are opt out rather than opt in.

The project documents the setting in the consuming project's package.json. In monorepos and alternative package managers, verify the effective configuration in the installation environment rather than assuming a particular workspace scope.

Browser mappings and the published package

Two helpers ship in a Node flavour and a browser flavour, and the `browser` field in the manifest swaps them. The map includes entries for source and generated directories:

"./src/helpers/btoa.node.js": "./src/helpers/btoa.browser.js",
"./lib/helpers/btoa.node.js": "./lib/helpers/btoa.browser.js",
"./es/helpers/btoa.node.js": "./es/helpers/btoa.browser.js"

The other helper is an AbortController polyfill with the same three-way treatment, for six mappings in total in the inspected manifest. Bundlers that honor the browser field select the corresponding browser implementations.

The catch is the `files` list. It names LICENSE, NOTICE, README.md, package.json, `lib`, `es`, `dist/swagger-client.browser.js`, `dist/swagger-client.browser.min.js` and the minified sourcemap. `src` is not in it. So the three `src` entries in the browser map describe files that never reach npm, and only the `lib` and `es` pairs can fire for a consumer of the published package.

Three entry points ship: require, import and a minified unpkg bundle

The manifest resolves three different ways depending on how it is loaded:

"main": "lib/commonjs.js",
"module": "es/index.js",
"unpkg": "dist/swagger-client.browser.min.js"

`main` is the CommonJS build, `module` and `jsnext:main` both point at the same ES module build, and `unpkg` names the minified browser bundle. The `files` list carries the unminified browser bundle and the sourcemap next to it, so a CDN can serve either form. The build script chain matches: `build` runs the UMD browser build, the commonjs build and the es build in sequence, and a separate `analyze:umd:browser` script points the source map explorer at the minified bundle to see what ended up inside it.

So the same source is transformed three ways, and the unpkg field points to a minified browser bundle; the appropriate artifact depends on the import path and tooling.

Features known to be missing from 3.x have their own document

The 3.x rewrite is acknowledged rather than hidden. Two documents sit under docs/migration: a migration guide for moving from 2.x to 3.x, and a second one referred to only by the name Graveyard, introduced for features known to be missing from 3.x.

The 2.x line is still reachable. Readers of the older version are pointed at the 2.x branch rather than at an archive, and the compatibility table keeps a row for 2.1.32 dated 2017-01-12 covering specification versions 1.0, 1.1 and 1.2, with a note that this release is only available on GitHub.

That gives the project an unusually honest shape: a current major, a documented list of what it dropped, and a branch for the previous one. What it does not give is a version mapping. The Graveyard names missing features without saying which client version reintroduced or permanently dropped them, so a reader has to reconcile that document against the release list by hand.

prepublishOnly runs clean, lint, test and build, and a hook checks every commit

The publish path is a single chain:

"prepublishOnly": "npm run clean && npm run lint && npm run test && npm run build"

Clean, lint, test, then build, all before anything is published. Underneath it the repository carries configuration for contributor checks, whose execution depends on the local hooks and CI setup: `.commitlintrc.json` for commit message rules, `.husky/` for git hooks, `.lintstagedrc` for staged file checks, `.eslintrc.js` and `.prettierrc` for style, `.editorconfig` for whitespace, and `.browserslistrc` for the browser targets the build targets. `.releaserc` holds the release configuration and `.nvmrc` pins the development runtime, with `config.deps_check_dir` set to `.deps_check` for a dependency check directory.

The current manifest also defines separate CommonJS, ES module and artifact-test scripts; inspect the version being built for the full command list.

Editorial conclusion

Swagger Client is an option for applications that fetch and resolve OpenAPI documents at runtime. Check the compatibility table and release notes for the exact version and specifications you need, test representative definitions, and review the Node and browser support policy before upgrading. The project documents installation analytics and opt-out settings; verify their behavior in your package manager and environment.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. swagger-api/swagger-client on GitHub