{"id":20597,"library":"swagger-jsdoc-webpack-plugin","title":"Swagger JSDoc Webpack Plugin","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/patsimm/swagger-jsdoc-webpack-plugin","tags":["javascript","swagger","jsdoc","webpack","plugin","typescript"],"install":[{"cmd":"npm install swagger-jsdoc-webpack-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add swagger-jsdoc-webpack-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add swagger-jsdoc-webpack-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency used to parse JSDoc and generate the OpenAPI spec","package":"swagger-jsdoc","optional":false},{"reason":"TypeScript type definitions for swagger-jsdoc (likely a dev dependency but bundled for type usage)","package":"@types/swagger-jsdoc","optional":true}],"imports":[{"note":"The package does not export a default ESM export; only CommonJS require works. For ESM projects, use dynamic import or a bundler shim.","wrong":"import SwaggerJSDocWebpackPlugin from 'swagger-jsdoc-webpack-plugin';","symbol":"SwaggerJSDocWebpackPlugin","correct":"const SwaggerJSDocWebpackPlugin = require('swagger-jsdoc-webpack-plugin');"},{"note":"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.","wrong":"const { SwaggerJSDocWebpackPlugin } = require('swagger-jsdoc-webpack-plugin');","symbol":"SwaggerJSDocWebpackPlugin","correct":"import SwaggerJSDocWebpackPlugin from 'swagger-jsdoc-webpack-plugin';"},{"note":"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.","wrong":"const { Options } = require('swagger-jsdoc-webpack-plugin');","symbol":"SwaggerJSDocWebpackPlugin.Options","correct":"import type { SwaggerJSDocWebpackPlugin } from 'swagger-jsdoc-webpack-plugin';"}],"quickstart":{"code":"const SwaggerJSDocWebpackPlugin = require('swagger-jsdoc-webpack-plugin');\n\nmodule.exports = {\n  // other webpack config\n  plugins: [\n    new SwaggerJSDocWebpackPlugin({\n      definition: {\n        openapi: '3.0.0',\n        info: {\n          title: 'My API',\n          version: '1.0.0',\n          description: 'API documentation generated from JSDoc',\n        },\n      },\n      apis: ['./src/**/*.js'],\n      outputFile: 'api-docs/swagger.json', // optional, default: 'swagger.json'\n    }),\n  ],\n};","lang":"javascript","description":"Configures the SwaggerJSDocWebpackPlugin in webpack.config.js to generate a swagger.json file from JSDoc annotations in source files, specifying OpenAPI metadata."},"warnings":[{"fix":"Set webpack configuration 'cache: false' or use 'watchOptions.ignored' to invalidate cache on JSDoc changes, or use webpack's snapshot management.","message":"The plugin does not support Webpack 5's persistent caching out of the box; it may not re-run on file changes if cached.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade to v2.1.0 or later to use custom output paths, or manually move/rename the generated file in a lifecycle hook.","message":"The 'outputFile' option was added in v2.1.0; earlier versions always generate 'swagger.json' in the output directory.","severity":"deprecated","affected_versions":"<2.1.0"},{"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.","message":"The 'apis' option expects an array of glob patterns relative to the project root; using patterns that match node_modules can cause issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Replace 'const { SwaggerJSDocWebpackPlugin } = require(...)' with 'const SwaggerJSDocWebpackPlugin = require(...)' if upgrading from v1.x.","message":"Version 2.0.0 changed the plugin's exported interface; it now uses a default export instead of named export.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Pin swagger-jsdoc to version 6.2.x (as used in v2.0.2+) or check the plugin's repository for newer commits.","message":"The package has not been updated since December 2022; swagger-jsdoc (dependency) may receive updates that break compatibility.","severity":"deprecated","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run 'npm install swagger-jsdoc-webpack-plugin --save-dev' (Webpack plugins are typically dev dependencies).","cause":"The package is not installed or not in node_modules.","error":"Error: Cannot find module 'swagger-jsdoc-webpack-plugin'"},{"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(...))'.","cause":"Using a named import from a CommonJS module that exports the plugin as default.","error":"TypeError: SwaggerJSDocWebpackPlugin is not a constructor"},{"fix":"Check the swagger-jsdoc options format; ensure 'definition' and 'apis' are correct. See swagger-jsdoc documentation for valid OpenAPI definition properties.","cause":"Passing invalid options to the plugin constructor.","error":"Webpack build fails with 'Invalid configuration object' regarding 'plugins[0]'"},{"fix":"Upgrade to swagger-jsdoc-webpack-plugin@2.1.0 or later.","cause":"Using version <2.1.0 which lacks the outputFile option.","error":"outputFile option ignored - always generates swagger.json"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}