Registry / web-framework / swagger-jsdoc-webpack-plugin

swagger-jsdoc-webpack-plugin

library2.1.0jsnpmunverified

Integrates swagger-jsdoc into Webpack to automatically generate a swagger.json file from JSDoc comments in your source files during the build process. The stable version is 2.1.0 (released 2022-12-17). It provides a convenient way to keep API documentation in sync with code by leveraging Webpack's compilation pipeline. Unlike manual generation scripts, this plugin integrates seamlessly into existing Webpack configs, supports custom output filenames, and passes all options directly to swagger-jsdoc. Ships TypeScript types. Note that the plugin had no releases after 2022 and may require manual dependency updates for security fixes.

web-framework devops

npm install swagger-jsdoc-webpack-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · SWAGGER-JSDOC-WEBP

swagger-jsdoc-webpack-plugin

web-frameworkjavascriptv2.1.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.

SwaggerJSDocWebpackPlugin

✓ const SwaggerJSDocWebpackPlugin = require('swagger-jsdoc-webpack-plugin');

✗ import SwaggerJSDocWebpackPlugin from 'swagger-jsdoc-webpack-plugin';

The package does not export a default ESM export; only CommonJS require works. For ESM projects, use dynamic import or a bundler shim.

SwaggerJSDocWebpackPlugin

✓ import SwaggerJSDocWebpackPlugin from 'swagger-jsdoc-webpack-plugin';

✗ const { SwaggerJSDocWebpackPlugin } = require('swagger-jsdoc-webpack-plugin');

V2.0+ uses a default export (CommonJS module.exports = Plugin), but TypeScript types may require default import. If using ESM, ensure your bundler handles CommonJS interop.

SwaggerJSDocWebpackPlugin.Options

✓ import type { SwaggerJSDocWebpackPlugin } from 'swagger-jsdoc-webpack-plugin';

✗ const { Options } = require('swagger-jsdoc-webpack-plugin');

The types are exported under the same name as the class. To use the Options type, you need to import the plugin's type namespace or use the Options from swagger-jsdoc directly.

Configures the SwaggerJSDocWebpackPlugin in webpack.config.js to generate a swagger.json file from JSDoc annotations in source files, specifying OpenAPI metadata.

const SwaggerJSDocWebpackPlugin = require('swagger-jsdoc-webpack-plugin'); module.exports = { // other webpack config plugins: [ new SwaggerJSDocWebpackPlugin({ definition: { openapi: '3.0.0', info: { title: 'My API', version: '1.0.0', description: 'API documentation generated from JSDoc', }, }, apis: ['./src/**/*.js'], outputFile: 'api-docs/swagger.json', // optional, default: 'swagger.json' }), ], };

Debug

Known issues

gotchaThe plugin does not support Webpack 5's persistent caching out of the box; it may not re-run on file changes if cached.

fix

Set webpack configuration 'cache: false' or use 'watchOptions.ignored' to invalidate cache on JSDoc changes, or use webpack's snapshot management.

affects: >=2.0.0

deprecatedThe 'outputFile' option was added in v2.1.0; earlier versions always generate 'swagger.json' in the output directory.

fix

Upgrade to v2.1.0 or later to use custom output paths, or manually move/rename the generated file in a lifecycle hook.

affects: <2.1.0

gotchaThe 'apis' option expects an array of glob patterns relative to the project root; using patterns that match node_modules can cause issues.

fix

Ensure apis patterns do not include node_modules (e.g., by using './src/**/*.js' instead of './**/*.js') or set the 'exclude' option if available.

affects: >=1.0.0

breakingVersion 2.0.0 changed the plugin's exported interface; it now uses a default export instead of named export.

fix

Replace 'const { SwaggerJSDocWebpackPlugin } = require(...)' with 'const SwaggerJSDocWebpackPlugin = require(...)' if upgrading from v1.x.

affects: >=2.0.0

deprecatedThe package has not been updated since December 2022; swagger-jsdoc (dependency) may receive updates that break compatibility.

fix

Pin swagger-jsdoc to version 6.2.x (as used in v2.0.2+) or check the plugin's repository for newer commits.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'swagger-jsdoc-webpack-plugin'

The package is not installed or not in node_modules.

fix

Run 'npm install swagger-jsdoc-webpack-plugin --save-dev' (Webpack plugins are typically dev dependencies).

TypeError: SwaggerJSDocWebpackPlugin is not a constructor

Using a named import from a CommonJS module that exports the plugin as default.

fix

Use 'const SwaggerJSDocWebpackPlugin = require('swagger-jsdoc-webpack-plugin');' or if using ESM, use dynamic import: 'await import('swagger-jsdoc-webpack-plugin').then(m => new m.default(...))'.

Webpack build fails with 'Invalid configuration object' regarding 'plugins[0]'

Passing invalid options to the plugin constructor.

fix

Check the swagger-jsdoc options format; ensure 'definition' and 'apis' are correct. See swagger-jsdoc documentation for valid OpenAPI definition properties.

outputFile option ignored - always generates swagger.json

Using version <2.1.0 which lacks the outputFile option.

fix

Upgrade to swagger-jsdoc-webpack-plugin@2.1.0 or later.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

swagger-jsdocrequiredCore dependency used to parse JSDoc and generate the OpenAPI spec

@types/swagger-jsdocoptionalTypeScript type definitions for swagger-jsdoc (likely a dev dependency but bundled for type usage)

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/patsimm/swagger-jsdoc-webpack-plugin ↗

packagehttps://www.npmjs.com/package/swagger-jsdoc-webpack-plugin ↗