0
# Springfox Swagger UI
1

2
Springfox Swagger UI provides a customized Swagger UI web interface packaged as a WebJar for Spring Boot applications. It automatically integrates with Springfox-generated API documentation, offering an interactive interface for API exploration and testing with Spring-specific enhancements including CSRF protection and OAuth2 support.
3

4
## Package Information
5

6
- **Package Name**: springfox-swagger-ui
7
- **Package Type**: maven
8
- **Language**: Java (packaging) + JavaScript/CSS/HTML (web assets)
9
- **Installation**: Add Maven dependency in `pom.xml` or Gradle dependency in `build.gradle`
10

11
Maven:
12
```xml
13
<dependency>
14
    <groupId>io.springfox</groupId>
15
    <artifactId>springfox-swagger-ui</artifactId>
16
    <version>3.0.0</version>
17
</dependency>
18
```
19

20
Gradle:
21
```gradle
22
implementation 'io.springfox:springfox-swagger-ui:3.0.0'
23
```
24

25
## Core Imports
26

27
Java (if needed for advanced configuration):
28
```java
29
import springfox.documentation.swagger.web.SecurityConfiguration;
30
import springfox.documentation.swagger.web.UiConfiguration;
31
```
32

33
JavaScript (if extending the UI):
34
```javascript
35
// Access global objects created by springfox.js
36
window.ui;          // SwaggerUIBundle instance
37
window.uiConfig;    // UI configuration
38
window.securityConfig; // Security configuration
39
```
40

41
## Basic Usage
42

43
### Standard Integration
44

45
For most Spring Boot applications with Springfox, simply add the dependency and the UI will be automatically available:
46

47
1. Add the Maven/Gradle dependency
48
2. Ensure you have Springfox configured in your application
49
3. Access the UI at: `http://localhost:8080/swagger-ui/index.html`
50

51
### Custom Base Path
52

53
Configure a custom base path in your `application.properties`:
54

55
```properties
56
springfox.documentation.swagger-ui.base-url=/custom-docs
57
```
58

59
Then access at: `http://localhost:8080/custom-docs/swagger-ui/index.html`
60

61
## Architecture
62

63
Springfox Swagger UI consists of several key components:
64

65
- **WebJar Structure**: Standard WebJar packaging under `/META-INF/resources/webjars/springfox-swagger-ui/{version}/`
66
- **Custom JavaScript**: Enhanced Swagger UI initialization with Spring-specific configuration
67
- **CSRF Integration**: Automatic CSRF token handling for Spring Security
68
- **Configuration Endpoints**: RESTful endpoints for dynamic UI and security configuration
69
- **Asset Management**: Custom fonts, CSS styling, and HTML templates
70

71
## Capabilities
72

73
### WebJar Integration
74

75
Access to packaged Swagger UI assets through standard WebJar URLs.
76

77
```java { .api }
78
// WebJar base path
79
/webjars/springfox-swagger-ui/{version}/
80

81
// Main entry points
82
/webjars/springfox-swagger-ui/{version}/index.html
83
/webjars/springfox-swagger-ui/{version}/springfox.js
84
/webjars/springfox-swagger-ui/{version}/springfox.css
85
```
86

87
### Configuration Endpoints
88

89
RESTful endpoints that provide dynamic configuration for the Swagger UI.
90

91
```java { .api }
92
// Base endpoint (configurable via springfox.documentation.swagger-ui.base-url)
93
GET /swagger-resources
94

95
// Configuration endpoints
96
GET /swagger-resources/configuration/ui
97
GET /swagger-resources/configuration/security
98
GET /swagger-resources
99
```
100

101
**Expected Response Types:**
102

103
```typescript { .api }
104
// UI Configuration Response
105
interface UiConfiguration {
106
  deepLinking: boolean;
107
  displayOperationId: boolean;
108
  defaultModelsExpandDepth: number;
109
  defaultModelExpandDepth: number;
110
  defaultModelRendering: string;
111
  displayRequestDuration: boolean;
112
  docExpansion: string;
113
  filter: boolean | string;
114
  maxDisplayedTags: number;
115
  operationsSorter: string;
116
  showExtensions: boolean;
117
  showCommonExtensions: boolean;
118
  tagSorter: string;
119
  supportedSubmitMethods: string[];
120
  validatorUrl: string;
121
  swaggerBaseUiUrl: string;
122
}
123

124
// Security Configuration Response
125
interface SecurityConfiguration {
126
  enableCsrfSupport: boolean;
127
  clientId: string;
128
  clientSecret: string;
129
  realm: string;
130
  appName: string;
131
  scopeSeparator: string;
132
  additionalQueryStringParams: Record<string, any>;
133
  useBasicAuthenticationWithAccessCodeGrant: boolean;
134
}
135

136
// Swagger Resources Response
137
interface SwaggerResource {
138
  name: string;
139
  url: string;
140
  swaggerVersion: string;
141
  location: string;
142
}
143
```
144

145
### JavaScript API
146

147
Core JavaScript functionality for initializing and customizing the Swagger UI.
148

149
```javascript { .api }
150
/**
151
 * Main initialization function that builds the Swagger UI system
152
 * @param baseUrl - Base URL for API endpoints
153
 * @returns Promise that resolves when UI is initialized
154
 */
155
async function buildSystemAsync(baseUrl: string): Promise<void>;
156

157
/**
158
 * Creates and configures the SwaggerUIBundle instance  
159
 * @param baseUrl - Base URL for API endpoints
160
 * @param resources - Array of swagger resources
161
 * @param configUI - UI configuration object
162
 * @param configSecurity - Security configuration object
163
 * @returns Configured SwaggerUIBundle instance
164
 */
165
function getUI(
166
  baseUrl: string,
167
  resources: SwaggerResource[],
168
  configUI: UiConfiguration,
169
  configSecurity: SecurityConfiguration
170
): SwaggerUIBundle;
171

172
/**
173
 * Extracts base URL from current window location
174
 * @returns Base URL string
175
 */
176
function getBaseURL(): string;
177

178
/**
179
 * Prepends base URL to resource URLs
180
 * @param baseUrl - Base URL to prepend
181
 * @param resources - Array of resources to modify
182
 * @returns Modified resources array
183
 */
184
function prependBaseUrl(baseUrl: string, resources: SwaggerResource[]): SwaggerResource[];
185
```
186

187
### CSRF Protection
188

189
Automatic CSRF token handling for Spring Security integration.
190

191
```javascript { .api }
192
/**
193
 * Adds CSRF header to all API requests if CSRF is enabled
194
 * This is the default export from the csrf module
195
 * @param baseUrl - Base URL for CSRF token retrieval
196
 * @returns Promise that resolves when CSRF support is configured
197
 */
198
export default async function patchRequestInterceptor(baseUrl: string): Promise<void>;
199

200
/**
201
 * Attempts to retrieve CSRF token using multiple strategies
202
 * @param baseUrl - Base URL for token endpoints
203
 * @returns Promise resolving to CSRF token info or undefined
204
 */
205
async function getCsrf(baseUrl: string): Promise<CsrfToken | undefined>;
206

207
/**
208
 * Retrieves CSRF token from HTML meta tags
209
 * @param baseUrl - Base URL for HTML page
210
 * @returns Promise resolving to CSRF token info or undefined
211
 */
212
async function getCsrfFromMeta(baseUrl: string): Promise<CsrfToken | undefined>;
213

214
/**
215
 * Retrieves CSRF token from dedicated endpoint
216
 * @param baseUrl - Base URL for CSRF endpoint
217
 * @returns Promise resolving to CSRF token info or undefined
218
 */
219
async function getCsrfFromEndpoint(baseUrl: string): Promise<CsrfToken | undefined>;
220

221
/**
222
 * Retrieves CSRF token from cookies
223
 * @returns CSRF token info or undefined
224
 */
225
function getCsrfFromCookie(): CsrfToken | undefined;
226

227
interface CsrfToken {
228
  headerName: string;
229
  token: string;
230
}
231
```
232

233
### Global JavaScript Objects
234

235
Objects available in the browser after UI initialization.
236

237
```javascript { .api }
238
// Global objects created after initialization
239
declare global {
240
  interface Window {
241
    /** Main Swagger UI instance */
242
    ui: SwaggerUIBundle;
243
    /** UI configuration object */
244
    uiConfig: UiConfiguration;
245
    /** Security configuration object */
246
    securityConfig: SecurityConfiguration;
247
  }
248
}
249
```
250

251
### Custom Styling
252

253
CSS customizations and font integration for Spring-specific branding.
254

255
```css { .api }
256
/* Main stylesheet */
257
/webjars/springfox-swagger-ui/{version}/springfox.css
258

259
/* Custom fonts included */
260
Titillium Web (regular, 600, 700)
261
Source Code Pro (300, 600)
262
Open Sans (regular, 700)
263
```
264

265
### Build System Integration
266

267
Gradle configuration for customizing and building the WebJar.
268

269
```gradle { .api }
270
// Key Gradle tasks available
271
task swaggerUiDownload    // Downloads official Swagger UI
272
task unzip                // Extracts Swagger UI distribution  
273
task npmBuild            // Builds custom JavaScript modules
274
task customizeSwaggerUi  // Applies Spring customizations
275
task jar                 // Packages as WebJar
276
```
277

278
## Configuration Examples
279

280
### Custom UI Configuration
281

282
Create a `UiConfiguration` bean to customize the Swagger UI:
283

284
```java
285
@Configuration
286
public class SwaggerUiConfig {
287
    
288
    @Bean
289
    public UiConfiguration uiConfig() {
290
        return UiConfigurationBuilder.builder()
291
            .deepLinking(true)
292
            .displayOperationId(false)
293
            .defaultModelsExpandDepth(1)
294
            .defaultModelExpandDepth(1)
295
            .defaultModelRendering(ModelRendering.EXAMPLE)
296
            .displayRequestDuration(false)
297
            .docExpansion(DocExpansion.NONE)
298
            .filter(false)
299
            .maxDisplayedTags(null)
300
            .operationsSorter(OperationsSorter.ALPHA)
301
            .showExtensions(false)
302
            .tagsSorter(TagsSorter.ALPHA)
303
            .supportedSubmitMethods(UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS)
304
            .validatorUrl(null)
305
            .build();
306
    }
307
}
308
```
309

310
### Custom Security Configuration
311

312
Create a `SecurityConfiguration` bean for OAuth2 setup:
313

314
```java
315
@Configuration
316
public class SwaggerSecurityConfig {
317
    
318
    @Bean
319
    public SecurityConfiguration security() {
320
        return SecurityConfigurationBuilder.builder()
321
            .clientId("swagger-ui")
322
            .clientSecret("swagger-ui-secret")
323
            .realm("swagger-ui-realm")
324
            .appName("swagger-ui")
325
            .scopeSeparator(",")
326
            .additionalQueryStringParams(null)
327
            .useBasicAuthenticationWithAccessCodeGrant(false)
328
            .build();
329
    }
330
}
331
```
332

333
### Enable CSRF Support
334

335
Enable CSRF protection in your security configuration:
336

337
```java
338
@Bean
339
public SecurityConfiguration securityConfiguration() {
340
    return SecurityConfigurationBuilder.builder()
341
        .enableCsrfSupport(true)
342
        .build();
343
}
344
```
345

346
## Error Handling
347

348
Common issues and troubleshooting:
349

350
### Base URL Resolution Issues
351

352
If the UI cannot automatically determine the base URL, it will prompt the user. This commonly occurs with:
353
- API Gateway configurations
354
- Dynamic servlet registration
355
- Proxy configurations
356

357
**Solution**: Manually configure the base URL or implement a custom base URL resolution strategy.
358

359
### CSRF Token Retrieval Failures
360

361
The CSRF module attempts three strategies:
362
1. HTML meta tags (`_csrf_header`, `_csrf`)
363
2. `/csrf` endpoint  
364
3. `XSRF-TOKEN` cookie
365

366
**Solution**: Ensure your Spring Security configuration provides CSRF tokens through one of these methods.
367

368
### Missing Configuration Endpoints
369

370
The UI expects these endpoints to be available:
371
- `/swagger-resources`
372
- `/swagger-resources/configuration/ui`
373
- `/swagger-resources/configuration/security`
374

375
**Solution**: Verify that `springfox-swagger-common` is included and properly configured.
376

377
## Types
378

379
### SwaggerUIBundle Configuration
380

381
```typescript { .api }
382
interface SwaggerUIBundleConfig {
383
  // Core configuration
384
  configUrl?: string | null;
385
  dom_id: string;
386
  dom_node?: HTMLElement | null;
387
  spec: object;
388
  url: string;
389
  urls: SwaggerResource[];
390
  
391
  // Plugin system
392
  layout: string;
393
  plugins: any[];
394
  presets: any[];
395
  
396
  // Display options
397
  deepLinking: boolean;
398
  displayOperationId: boolean;
399
  defaultModelsExpandDepth: number;
400
  defaultModelExpandDepth: number;
401
  defaultModelRendering: string;
402
  displayRequestDuration: boolean;
403
  docExpansion: string;
404
  filter: boolean | string;
405
  maxDisplayedTags: number | null;
406
  operationsSorter: string;
407
  showExtensions: boolean;
408
  showCommonExtensions: boolean;
409
  tagSorter: string;
410
  
411
  // Network configuration
412
  oauth2RedirectUrl: string;
413
  requestInterceptor: (request: any) => any;
414
  responseInterceptor: (response: any) => any;
415
  showMutatedRequest: boolean;
416
  supportedSubmitMethods: string[];
417
  validatorUrl: string | null;
418
  
419
  // Custom configuration
420
  custom: {
421
    enableCsrfSupport: boolean;
422
  };
423
}
424
```
425

426
### OAuth Configuration
427

428
```typescript { .api }
429
interface OAuthConfig {
430
  clientId: string;
431
  clientSecret: string;
432
  realm: string;
433
  appName: string;
434
  scopeSeparator: string;
435
  additionalQueryStringParams: Record<string, any>;
436
  useBasicAuthenticationWithAccessCodeGrant: boolean;
437
}
438
```