0
# Swagger UI Dist
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: swagger-ui-dist
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install swagger-ui-dist`
10

11
## Core Imports
12

13
```javascript
14
const { SwaggerUIBundle, SwaggerUIStandalonePreset, getAbsoluteFSPath } = require("swagger-ui-dist");
15
```
16

17
ES Modules:
18

19
```javascript
20
import { SwaggerUIBundle, SwaggerUIStandalonePreset, getAbsoluteFSPath } from "swagger-ui-dist";
21
```
22

23
## Basic Usage
24

25
### Static File Serving
26

27
```javascript
28
const swaggerUiAssetPath = require("swagger-ui-dist").getAbsoluteFSPath();
29

30
// Express.js example
31
app.use('/swagger-ui', express.static(swaggerUiAssetPath));
32
```
33

34
### Component Usage
35

36
```javascript
37
import { SwaggerUIBundle, SwaggerUIStandalonePreset } from "swagger-ui-dist";
38

39
// Initialize Swagger UI
40
SwaggerUIBundle({
41
  url: "https://petstore.swagger.io/v2/swagger.json",
42
  dom_id: "#swagger-ui",
43
  deepLinking: true,
44
  presets: [
45
    SwaggerUIBundle.presets.apis,
46
    SwaggerUIStandalonePreset
47
  ],
48
  plugins: [
49
    SwaggerUIBundle.plugins.DownloadUrl
50
  ],
51
  layout: "StandaloneLayout"
52
});
53
```
54

55
## Architecture
56

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

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

65
## Capabilities
66

67
### SwaggerUI Bundle
68

69
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.
70

71
```javascript { .api }
72
function SwaggerUIBundle(options: SwaggerUIOptions): SwaggerUISystem;
73

74
// Static properties
75
SwaggerUIBundle.presets: {
76
  apis: PresetApisFunction;
77
  base: PresetBaseFunction;
78
};
79

80
SwaggerUIBundle.plugins: {
81
  Auth: AuthPlugin;
82
  Configs: ConfigsPlugin;
83
  DeepLining: DeepLinkingPlugin;
84
  Err: ErrPlugin;
85
  Filter: FilterPlugin;
86
  Icons: IconsPlugin;
87
  JSONSchema5: JSONSchema5Plugin;
88
  JSONSchema5Samples: JSONSchema5SamplesPlugin;
89
  JSONSchema202012: JSONSchema202012Plugin;
90
  JSONSchema202012Samples: JSONSchema202012SamplesPlugin;
91
  Layout: LayoutPlugin;
92
  Logs: LogsPlugin;
93
  OpenAPI30: OpenAPI30Plugin;
94
  OpenAPI31: OpenAPI31Plugin;
95
  OnComplete: OnCompletePlugin;
96
  RequestSnippets: RequestSnippetsPlugin;
97
  Spec: SpecPlugin;
98
  SwaggerClient: SwaggerClientPlugin;
99
  Util: UtilPlugin;
100
  View: ViewPlugin;
101
  ViewLegacy: ViewLegacyPlugin;
102
  DownloadUrl: DownloadUrlPlugin;
103
  SyntaxHighlighting: SyntaxHighlightingPlugin;
104
  Versions: VersionsPlugin;
105
  SafeRender: SafeRenderPlugin;
106
};
107

108
interface SwaggerUIOptions {
109
  url?: string;
110
  urls?: Array<{ url: string; name: string }>;
111
  spec?: object;
112
  dom_id?: string;
113
  domNode?: Element;
114
  configUrl?: string;
115
  deepLinking?: boolean;
116
  displayOperationId?: boolean;
117
  defaultModelsExpandDepth?: number;
118
  defaultModelExpandDepth?: number;
119
  defaultModelRendering?: 'example' | 'model';
120
  displayRequestDuration?: boolean;
121
  docExpansion?: 'list' | 'full' | 'none';
122
  filter?: boolean | string;
123
  maxDisplayedTags?: number;
124
  showExtensions?: boolean;
125
  showCommonExtensions?: boolean;
126
  useUnsafeMarkdown?: boolean;
127
  onComplete?: () => void;
128
  syntaxHighlight?: {
129
    activated?: boolean;
130
    theme?: string;
131
  };
132
  tryItOutEnabled?: boolean;
133
  requestSnippetsEnabled?: boolean;
134
  requestSnippets?: {
135
    generators?: object;
136
    defaultExpanded?: boolean;
137
    languages?: string[];
138
  };
139
  supportedSubmitMethods?: string[];
140
  validatorUrl?: string | null;
141
  withCredentials?: boolean;
142
  modelPropertyMacro?: () => void;
143
  parameterMacro?: () => void;
144
  presets?: Array<any>;
145
  plugins?: Array<any>;
146
  layout?: string;
147
  persistAuthorization?: boolean;
148
}
149

150
interface SwaggerUISystem {
151
  render: (domNode: Element | string, component: string) => void;
152
  specActions: {
153
    updateUrl: (url: string) => void;
154
    updateLoadingStatus: (status: string) => void;
155
    updateSpec: (spec: string) => void;
156
    download: (url: string) => void;
157
  };
158
  configsActions: {
159
    loaded: () => void;
160
  };
161
}
162
```
163

164
### SwaggerUI Standalone Preset
165

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

168
```javascript { .api }
169
const SwaggerUIStandalonePreset: Array<SwaggerUIPlugin>;
170

171
interface SwaggerUIPlugin {
172
  // Plugin implementation details
173
}
174
```
175

176
### Static File Path Access
177

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

180
```javascript { .api }
181
/**
182
 * Returns the absolute filesystem path to the swagger-ui-dist directory
183
 * @returns Absolute path string for static file serving
184
 * @throws Error when called outside Node.js environment
185
 */
186
function getAbsoluteFSPath(): string;
187

188
/**
189
 * Legacy alias for getAbsoluteFSPath - identical functionality
190
 * @returns Absolute path string for static file serving  
191
 * @throws Error when called outside Node.js environment
192
 */
193
function absolutePath(): string;
194
```
195

196
## Static Assets
197

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

200
- **CSS Files**: 
201
  - `swagger-ui.css` - Complete styling for Swagger UI interface
202
  - `swagger-ui.css.map` - Source map for CSS debugging
203
  - `index.css` - Additional index-specific styles
204
- **JavaScript Bundles**: 
205
  - `swagger-ui-bundle.js` - Main UMD bundle with all functionality
206
  - `swagger-ui-bundle.js.map` - Source map for main bundle
207
  - `swagger-ui-standalone-preset.js` - Standalone preset bundle
208
  - `swagger-ui-standalone-preset.js.map` - Source map for preset
209
  - `swagger-ui.js` - Core UI bundle
210
  - `swagger-ui.js.map` - Source map for core bundle
211
  - `swagger-ui-es-bundle.js` - ES module bundle
212
  - `swagger-ui-es-bundle.js.map` - Source map for ES bundle
213
  - `swagger-ui-es-bundle-core.js` - ES module core bundle
214
  - `swagger-ui-es-bundle-core.js.map` - Source map for ES core
215
- **HTML Templates**: 
216
  - `index.html` - Default Swagger UI HTML page
217
  - `oauth2-redirect.html` - OAuth2 redirect handler
218
- **Configuration**: 
219
  - `swagger-initializer.js` - Default initialization script
220
- **Icons**: 
221
  - `favicon-16x16.png` - 16x16 favicon
222
  - `favicon-32x32.png` - 32x32 favicon
223

224
## Error Handling
225

226
The package implements graceful error handling:
227

228
- **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
229
- **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
230
- **Missing DOM Elements**: SwaggerUIBundle logs console errors when neither `dom_id` nor `domNode` options are specified
231
- **Configuration Loading**: Async configuration loading handles network failures gracefully when using `configUrl` option
232
- **Parameter Validation**: Functions handle missing or invalid parameters by using default values or providing appropriate fallbacks
233

234
## Environment Compatibility
235

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

241
## Analytics
242

243
Optional analytics via Scarf.sh:
244
- Only runs during npm installation, not at runtime
245
- Can be disabled via `scarfSettings.enabled = false` in package.json
246
- Can be disabled via `SCARF_ANALYTICS=false` environment variable
247

248
## Types
249

250
```javascript { .api }
251
// Note: This package provides JavaScript without built-in TypeScript definitions
252
// Types shown here are for documentation purposes
253

254
interface SwaggerUIConfig {
255
  url?: string;
256
  spec?: object;
257
  dom_id?: string;
258
  domNode?: Element;
259
  presets?: Array<any>;
260
  plugins?: Array<any>;
261
  layout?: string;
262
  // ... other configuration options as shown in SwaggerUIOptions above
263
}
264

265
interface StaticAssets {
266
  css: string[];
267
  js: string[];
268
  html: string[];
269
  images: string[];
270
}
271

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

276
interface SwaggerUIPlugin {
277
  // Plugin objects contain functions and configuration
278
  // Specific structure varies by plugin type
279
}
280

281
// Plugin types available through SwaggerUIBundle.plugins
282
interface AuthPlugin extends SwaggerUIPlugin {}
283
interface ConfigsPlugin extends SwaggerUIPlugin {}
284
interface DeepLinkingPlugin extends SwaggerUIPlugin {}
285
interface ErrPlugin extends SwaggerUIPlugin {}
286
interface FilterPlugin extends SwaggerUIPlugin {}
287
interface IconsPlugin extends SwaggerUIPlugin {}
288
interface JSONSchema5Plugin extends SwaggerUIPlugin {}
289
interface JSONSchema5SamplesPlugin extends SwaggerUIPlugin {}
290
interface JSONSchema202012Plugin extends SwaggerUIPlugin {}
291
interface JSONSchema202012SamplesPlugin extends SwaggerUIPlugin {}
292
interface LayoutPlugin extends SwaggerUIPlugin {}
293
interface LogsPlugin extends SwaggerUIPlugin {}
294
interface OpenAPI30Plugin extends SwaggerUIPlugin {}
295
interface OpenAPI31Plugin extends SwaggerUIPlugin {}
296
interface OnCompletePlugin extends SwaggerUIPlugin {}
297
interface RequestSnippetsPlugin extends SwaggerUIPlugin {}
298
interface SpecPlugin extends SwaggerUIPlugin {}
299
interface SwaggerClientPlugin extends SwaggerUIPlugin {}
300
interface UtilPlugin extends SwaggerUIPlugin {}
301
interface ViewPlugin extends SwaggerUIPlugin {}
302
interface ViewLegacyPlugin extends SwaggerUIPlugin {}
303
interface DownloadUrlPlugin extends SwaggerUIPlugin {}
304
interface SyntaxHighlightingPlugin extends SwaggerUIPlugin {}
305
interface VersionsPlugin extends SwaggerUIPlugin {}
306
interface SafeRenderPlugin extends SwaggerUIPlugin {}
307
```