or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-swagger-ui-dist

Dependency-free distribution of Swagger UI for serving interactive OpenAPI documentation from server-side projects and single-page applications

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/swagger-ui-dist@5.28.x

To install, run

npx @tessl/cli install tessl/npm-swagger-ui-dist@5.28.0

Swagger UI Dist

Swagger UI Dist is a dependency-free distribution package that provides everything needed to serve Swagger UI in server-side projects or single-page applications. It exposes the entire Swagger UI distribution folder as a standalone module without requiring npm dependency resolution, making it ideal for environments where traditional dependency management isn't feasible.

Package Information

Package Name: swagger-ui-dist
Package Type: npm
Language: JavaScript
Installation: npm install swagger-ui-dist

Core Imports

const { SwaggerUIBundle, SwaggerUIStandalonePreset, getAbsoluteFSPath } = require("swagger-ui-dist");

ES Modules:

import { SwaggerUIBundle, SwaggerUIStandalonePreset, getAbsoluteFSPath } from "swagger-ui-dist";

Basic Usage

Static File Serving

const swaggerUiAssetPath = require("swagger-ui-dist").getAbsoluteFSPath();

// Express.js example
app.use('/swagger-ui', express.static(swaggerUiAssetPath));

Component Usage

import { SwaggerUIBundle, SwaggerUIStandalonePreset } from "swagger-ui-dist";

// Initialize Swagger UI
SwaggerUIBundle({
  url: "https://petstore.swagger.io/v2/swagger.json",
  dom_id: "#swagger-ui",
  deepLinking: true,
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUIBundle.plugins.DownloadUrl
  ],
  layout: "StandaloneLayout"
});

Architecture

The swagger-ui-dist package is built around several key components:

SwaggerUIBundle: Main constructor/class for creating interactive API documentation interfaces
SwaggerUIStandalonePreset: Minimal plugin preset for standalone implementations
Static Assets: Complete distribution of CSS, JavaScript, HTML, and other assets
File System Integration: Direct access to asset paths for static file serving
Environment Compatibility: Graceful handling for both Node.js and browser environments

Capabilities

SwaggerUI Bundle

Core SwaggerUI constructor for creating interactive OpenAPI documentation interfaces. Supports full customization with plugins, presets, and configuration options. Also provides static properties for accessing built-in presets and plugins.

function SwaggerUIBundle(options: SwaggerUIOptions): SwaggerUISystem;

// Static properties
SwaggerUIBundle.presets: {
  apis: PresetApisFunction;
  base: PresetBaseFunction;
};

SwaggerUIBundle.plugins: {
  Auth: AuthPlugin;
  Configs: ConfigsPlugin;
  DeepLining: DeepLinkingPlugin;
  Err: ErrPlugin;
  Filter: FilterPlugin;
  Icons: IconsPlugin;
  JSONSchema5: JSONSchema5Plugin;
  JSONSchema5Samples: JSONSchema5SamplesPlugin;
  JSONSchema202012: JSONSchema202012Plugin;
  JSONSchema202012Samples: JSONSchema202012SamplesPlugin;
  Layout: LayoutPlugin;
  Logs: LogsPlugin;
  OpenAPI30: OpenAPI30Plugin;
  OpenAPI31: OpenAPI31Plugin;
  OnComplete: OnCompletePlugin;
  RequestSnippets: RequestSnippetsPlugin;
  Spec: SpecPlugin;
  SwaggerClient: SwaggerClientPlugin;
  Util: UtilPlugin;
  View: ViewPlugin;
  ViewLegacy: ViewLegacyPlugin;
  DownloadUrl: DownloadUrlPlugin;
  SyntaxHighlighting: SyntaxHighlightingPlugin;
  Versions: VersionsPlugin;
  SafeRender: SafeRenderPlugin;
};

interface SwaggerUIOptions {
  url?: string;
  urls?: Array<{ url: string; name: string }>;
  spec?: object;
  dom_id?: string;
  domNode?: Element;
  configUrl?: string;
  deepLinking?: boolean;
  displayOperationId?: boolean;
  defaultModelsExpandDepth?: number;
  defaultModelExpandDepth?: number;
  defaultModelRendering?: 'example' | 'model';
  displayRequestDuration?: boolean;
  docExpansion?: 'list' | 'full' | 'none';
  filter?: boolean | string;
  maxDisplayedTags?: number;
  showExtensions?: boolean;
  showCommonExtensions?: boolean;
  useUnsafeMarkdown?: boolean;
  onComplete?: () => void;
  syntaxHighlight?: {
    activated?: boolean;
    theme?: string;
  };
  tryItOutEnabled?: boolean;
  requestSnippetsEnabled?: boolean;
  requestSnippets?: {
    generators?: object;
    defaultExpanded?: boolean;
    languages?: string[];
  };
  supportedSubmitMethods?: string[];
  validatorUrl?: string | null;
  withCredentials?: boolean;
  modelPropertyMacro?: () => void;
  parameterMacro?: () => void;
  presets?: Array<any>;
  plugins?: Array<any>;
  layout?: string;
  persistAuthorization?: boolean;
}

interface SwaggerUISystem {
  render: (domNode: Element | string, component: string) => void;
  specActions: {
    updateUrl: (url: string) => void;
    updateLoadingStatus: (status: string) => void;
    updateSpec: (spec: string) => void;
    download: (url: string) => void;
  };
  configsActions: {
    loaded: () => void;
  };
}

SwaggerUI Standalone Preset

Minimal plugin preset for standalone Swagger UI implementations, providing essential plugins without additional dependencies.

const SwaggerUIStandalonePreset: Array<SwaggerUIPlugin>;

interface SwaggerUIPlugin {
  // Plugin implementation details
}

Static File Path Access

Returns the absolute filesystem path to the swagger-ui-dist directory for serving static assets.

/**
 * Returns the absolute filesystem path to the swagger-ui-dist directory
 * @returns Absolute path string for static file serving
 * @throws Error when called outside Node.js environment
 */
function getAbsoluteFSPath(): string;

/**
 * Legacy alias for getAbsoluteFSPath - identical functionality
 * @returns Absolute path string for static file serving  
 * @throws Error when called outside Node.js environment
 */
function absolutePath(): string;

Static Assets

The package includes all necessary static assets in the dist folder:

CSS Files:
- swagger-ui.css - Complete styling for Swagger UI interface
- swagger-ui.css.map - Source map for CSS debugging
- index.css - Additional index-specific styles
JavaScript Bundles:
- swagger-ui-bundle.js - Main UMD bundle with all functionality
- swagger-ui-bundle.js.map - Source map for main bundle
- swagger-ui-standalone-preset.js - Standalone preset bundle
- swagger-ui-standalone-preset.js.map - Source map for preset
- swagger-ui.js - Core UI bundle
- swagger-ui.js.map - Source map for core bundle
- swagger-ui-es-bundle.js - ES module bundle
- swagger-ui-es-bundle.js.map - Source map for ES bundle
- swagger-ui-es-bundle-core.js - ES module core bundle
- swagger-ui-es-bundle-core.js.map - Source map for ES core
HTML Templates:
- index.html - Default Swagger UI HTML page
- oauth2-redirect.html - OAuth2 redirect handler
Configuration:
- swagger-initializer.js - Default initialization script
Icons:
- favicon-16x16.png - 16x16 favicon
- favicon-32x32.png - 32x32 favicon

Error Handling

The package implements graceful error handling:

SwaggerUI Import Failures: SwaggerUI bundle imports in index.js are wrapped in try-catch blocks to prevent module loading failures in browser environments where the bundles may not be available
File System Access: getAbsoluteFSPath throws an explicit Error with message "getAbsoluteFSPath can only be called within a Nodejs environment" when called outside Node.js environment
Missing DOM Elements: SwaggerUIBundle logs console errors when neither dom_id nor domNode options are specified
Configuration Loading: Async configuration loading handles network failures gracefully when using configUrl option
Parameter Validation: Functions handle missing or invalid parameters by using default values or providing appropriate fallbacks

Environment Compatibility

Node.js: Full functionality including file system path access
Browser: Component imports work, file system functions throw appropriate errors
Module Systems: Supports CommonJS, ES modules, and UMD formats
Build Tools: Compatible with webpack, rollup, and other bundlers

Analytics

Optional analytics via Scarf.sh:

Only runs during npm installation, not at runtime
Can be disabled via scarfSettings.enabled = false in package.json
Can be disabled via SCARF_ANALYTICS=false environment variable

Types

// Note: This package provides JavaScript without built-in TypeScript definitions
// Types shown here are for documentation purposes

interface SwaggerUIConfig {
  url?: string;
  spec?: object;
  dom_id?: string;
  domNode?: Element;
  presets?: Array<any>;
  plugins?: Array<any>;
  layout?: string;
  // ... other configuration options as shown in SwaggerUIOptions above
}

interface StaticAssets {
  css: string[];
  js: string[];
  html: string[];
  images: string[];
}

// Plugin and preset type definitions
type PresetApisFunction = () => Array<SwaggerUIPlugin>;
type PresetBaseFunction = () => Array<SwaggerUIPlugin>;

interface SwaggerUIPlugin {
  // Plugin objects contain functions and configuration
  // Specific structure varies by plugin type
}

// Plugin types available through SwaggerUIBundle.plugins
interface AuthPlugin extends SwaggerUIPlugin {}
interface ConfigsPlugin extends SwaggerUIPlugin {}
interface DeepLinkingPlugin extends SwaggerUIPlugin {}
interface ErrPlugin extends SwaggerUIPlugin {}
interface FilterPlugin extends SwaggerUIPlugin {}
interface IconsPlugin extends SwaggerUIPlugin {}
interface JSONSchema5Plugin extends SwaggerUIPlugin {}
interface JSONSchema5SamplesPlugin extends SwaggerUIPlugin {}
interface JSONSchema202012Plugin extends SwaggerUIPlugin {}
interface JSONSchema202012SamplesPlugin extends SwaggerUIPlugin {}
interface LayoutPlugin extends SwaggerUIPlugin {}
interface LogsPlugin extends SwaggerUIPlugin {}
interface OpenAPI30Plugin extends SwaggerUIPlugin {}
interface OpenAPI31Plugin extends SwaggerUIPlugin {}
interface OnCompletePlugin extends SwaggerUIPlugin {}
interface RequestSnippetsPlugin extends SwaggerUIPlugin {}
interface SpecPlugin extends SwaggerUIPlugin {}
interface SwaggerClientPlugin extends SwaggerUIPlugin {}
interface UtilPlugin extends SwaggerUIPlugin {}
interface ViewPlugin extends SwaggerUIPlugin {}
interface ViewLegacyPlugin extends SwaggerUIPlugin {}
interface DownloadUrlPlugin extends SwaggerUIPlugin {}
interface SyntaxHighlightingPlugin extends SwaggerUIPlugin {}
interface VersionsPlugin extends SwaggerUIPlugin {}
interface SafeRenderPlugin extends SwaggerUIPlugin {}