Swagger JSDoc Webpack Plugin

2.1.0 verified Sat Apr 25 auth: no javascript

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.

Common errors

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

cause 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).

error TypeError: SwaggerJSDocWebpackPlugin is not a constructor ↓

cause 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(...))'.

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

cause 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.

error outputFile option ignored - always generates swagger.json ↓

cause Using version <2.1.0 which lacks the outputFile option.

fix

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

Warnings

gotcha The 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.

deprecated The '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.

gotcha The '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.

breaking Version 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.

deprecated The 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.

Install

npm install swagger-jsdoc-webpack-plugin

yarn add swagger-jsdoc-webpack-plugin

pnpm add swagger-jsdoc-webpack-plugin

Imports

SwaggerJSDocWebpackPlugin
wrong
```
import SwaggerJSDocWebpackPlugin from 'swagger-jsdoc-webpack-plugin';
```
correct
```
const SwaggerJSDocWebpackPlugin = require('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
wrong
```
const { SwaggerJSDocWebpackPlugin } = require('swagger-jsdoc-webpack-plugin');
```
correct
```
import SwaggerJSDocWebpackPlugin from '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
wrong
```
const { Options } = require('swagger-jsdoc-webpack-plugin');
```
correct
```
import type { SwaggerJSDocWebpackPlugin } from '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.

Quickstart

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'
    }),
  ],
};