Swagger UI Dist

Common errors

• Error: getAbsoluteFSPath can only be called within a Nodejs environment

  cause Attempting to call `require('swagger-ui-dist').getAbsoluteFSPath()` or `import { getAbsoluteFSPath } from 'swagger-ui-dist'` in a browser environment.
  fix This function is server-side only. Call `getAbsoluteFSPath` in your Node.js application to resolve the path and then serve those files. Do not include this call in client-side code that runs in a browser.

• ReferenceError: SwaggerUIBundle is not defined

  cause The `swagger-ui-bundle.js` script was not correctly loaded or executed in the HTML page before `SwaggerUIBundle` was accessed.
  fix Verify that your HTML includes `<script src="/swagger-ui/swagger-ui-bundle.js"></script>` and that the path is correct and accessible by your web server. Ensure the initialization script runs after the bundle is loaded.

• Cannot find module 'swagger-ui-dist'

  cause The `swagger-ui-dist` package has not been installed or cannot be resolved by your module loader.
  fix Run `npm install swagger-ui-dist` or `yarn add swagger-ui-dist` in your project directory. Ensure your Node.js process has access to `node_modules`.

Warnings

• gotcha The `swagger-ui-dist` package uses Scarf for anonymized installation analytics, which runs during `npm install`. This data helps maintainers. Users can opt out by setting `scarfSettings.enabled: false` in `package.json` or `SCARF_ANALYTICS=false` environment variable during installation.
  Fix: To opt out, add `"scarfSettings": { "enabled": false }` to your `package.json` or run `SCARF_ANALYTICS=false npm install`.
• breaking Versions 5.32.2 and 5.32.4 addressed several high-severity CVEs by upgrading alpine packages, libpng, and zlib (e.g., CVE-2026-33416, CVE-2026-33636, CVE-2026-22184). Older versions are vulnerable to these issues.
  Fix: Upgrade to `swagger-ui-dist@5.32.4` or higher to ensure these critical security vulnerabilities are patched.
• gotcha This package, `swagger-ui-dist`, is specifically for serving static assets and is 'dependency-free'. If you intend to use Swagger UI programmatically within a bundler like Webpack or Browserify, `swagger-ui` (without '-dist') is often the more suitable package, as it handles its own dependencies.
  Fix: If integrating into a modern JavaScript build pipeline, consider using the `swagger-ui` package directly instead of `swagger-ui-dist`.
• gotcha The `getAbsoluteFSPath` function is designed for Node.js environments. Attempting to call `getAbsoluteFSPath()` in a browser environment will result in an error, as it relies on Node.js-specific modules like `path`.
  Fix: Ensure `getAbsoluteFSPath` is only invoked in your Node.js server-side code, not within client-side bundles.

Install

• npm install swagger-ui-dist npm
• yarn add swagger-ui-dist yarn
• pnpm add swagger-ui-dist pnpm

Imports

• SwaggerUIBundle
  wrong:

  const SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle

  correct:

  import { SwaggerUIBundle } from 'swagger-ui-dist'

  Primarily consumed in browser contexts after serving. For server-side Node.js ESM, use named import. CommonJS `require` for UI components is typically incorrect for this package's bundle usage.
• SwaggerUIStandalonePreset
  wrong:

  const SwaggerUIStandalonePreset = require('swagger-ui-dist').SwaggerUIStandalonePreset

  correct:

  import { SwaggerUIStandalonePreset } from 'swagger-ui-dist'

  Used as a plugin preset for Swagger UI. Similar to SwaggerUIBundle, for browser consumption.
• getAbsoluteFSPath
  wrong:

  import { getAbsoluteFSPath } from 'swagger-ui-dist'

  correct:

  const getAbsoluteFSPath = require('swagger-ui-dist').getAbsoluteFSPath

  This utility function is specifically for Node.js environments to get the filesystem path to the 'dist' assets and is primarily exported via CommonJS. It will throw an error if called outside Node.js.

Quickstart

Sets up an Express.js server to serve Swagger UI from its 'dist' folder, providing an API documentation endpoint.

const express = require('express');
const path = require('path');
const swaggerUiDist = require('swagger-ui-dist');

const app = express();
const port = 3000;

// Get the absolute file system path to the swagger-ui-dist directory
const swaggerUiAssetPath = swaggerUiDist.getAbsoluteFSPath();

// Serve the static Swagger UI files from the node_modules directory
app.use('/swagger-ui', express.static(swaggerUiAssetPath));

// Endpoint to display Swagger UI
app.get('/api-docs', (req, res) => {
  const swaggerSpecUrl = '/swagger.json'; // URL to your OpenAPI spec

  res.send(`
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Swagger UI</title>
        <link rel="stylesheet" type="text/css" href="/swagger-ui/swagger-ui.css" />
        <link rel="icon" type="image/png" href="/swagger-ui/favicon-32x32.png" sizes="32x32" />
        <link rel="icon" type="image/png" href="/swagger-ui/favicon-16x16.png" sizes="16x16" />
        <style>
            html { box-sizing: border-box; overflow: -moz-scrollbars-vertical; overflow-y: scroll; }
            *, *:before, *:after { box-sizing: inherit; }
            body { margin:0; background: #fafafa; }
        </style>
    </head>
    <body>
        <div id="swagger-ui"></div>
        <script src="/swagger-ui/swagger-ui-bundle.js" charset="UTF-8"> </script>
        <script src="/swagger-ui/swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
        <script>
            window.onload = function() {
                const ui = SwaggerUIBundle({
                    url: "${swaggerSpecUrl}",
                    dom_id: '#swagger-ui',
                    deepLinking: true,
                    presets: [
                        SwaggerUIBundle.presets.apis,
                        SwaggerUIStandalonePreset
                    ],
                    plugins: [
                        SwaggerUIBundle.plugins.DownloadUrl
                    ],
                    layout: "StandaloneLayout"
                });
                window.ui = ui;
            };
        </script>
    </body>
    </html>
  `);
});

// Example API spec endpoint
app.get('/swagger.json', (req, res) => {
  res.json({
    openapi: '3.0.0',
    info: {
      title: 'Example API',
      version: '1.0.0',
      description: 'A simple example API served with Swagger UI.',
    },
    paths: {
      '/hello': {
        get: {
          summary: 'Returns a greeting',
          responses: {
            '200': {
              description: 'Successful response',
              content: {
                'application/json': {
                  schema: {
                    type: 'object',
                    properties: {
                      message: {
                        type: 'string',
                        example: 'Hello from Example API!',
                      },
                    },
                  },
                },
              },
            },
          },
        },
      },
    },
  });
});

app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
  console.log(`Swagger UI available at http://localhost:${port}/api-docs`);
});