0
# Web Controllers
1

2
REST controllers and web endpoints that handle Swagger UI page requests, redirects, and configuration endpoints for both standard and actuator deployments.
3

4
## Capabilities
5

6
### SwaggerConfigResource
7

8
REST controller that provides JSON configuration endpoint for Swagger UI initialization.
9

10
```java { .api }
11
/**
12
 * REST controller providing JSON configuration for Swagger UI
13
 * Serves configuration data needed by the Swagger UI JavaScript application
14
 */
15
@RestController
16
public class SwaggerConfigResource {
17
    
18
    /**
19
     * Constructor requiring common welcome functionality
20
     * @param swaggerWelcomeCommon Common functionality for URL building and configuration
21
     */
22
    public SwaggerConfigResource(SwaggerWelcomeCommon swaggerWelcomeCommon);
23

24
    /**
25
     * Returns OpenAPI configuration as JSON for Swagger UI initialization
26
     * Provides URLs, paths, and settings required by the Swagger UI frontend
27
     * @param request HTTP request for context path and URL building
28
     * @return Map containing configuration parameters for Swagger UI
29
     */
30
    @Operation(hidden = true)
31
    @GetMapping(value = "/v3/api-docs/swagger-config", produces = MediaType.APPLICATION_JSON_VALUE)
32
    public Map<String, Object> openapiJson(HttpServletRequest request);
33
}
34
```
35

36
**Usage Example:**
37

38
```java
39
// Configuration is automatically served at /v3/api-docs/swagger-config
40
// JavaScript in Swagger UI fetches this to initialize the interface
41
```
42

43
### SwaggerWelcomeWebMvc
44

45
Controller that handles Swagger UI welcome page and redirects for standard Spring WebMVC applications.
46

47
```java { .api }
48
/**
49
 * Controller handling Swagger UI welcome page and redirects for WebMVC applications
50
 * Extends SwaggerWelcomeCommon for shared URL building and configuration logic
51
 */
52
@Controller
53
public class SwaggerWelcomeWebMvc extends SwaggerWelcomeCommon {
54
    
55
    /**
56
     * Constructor for WebMVC-specific welcome controller
57
     * @param swaggerUiConfig Swagger UI configuration properties
58
     * @param springDocConfigProperties SpringDoc configuration properties
59
     * @param springWebProvider Spring web provider for WebMVC-specific functionality
60
     */
61
    public SwaggerWelcomeWebMvc(SwaggerUiConfigProperties swaggerUiConfig, 
62
        SpringDocConfigProperties springDocConfigProperties, SpringWebProvider springWebProvider);
63

64
    /**
65
     * Handles requests to Swagger UI path and redirects to actual UI location
66
     * Builds proper redirect URL considering context paths and servlet paths
67
     * @param request HTTP request for context and path information
68
     * @return ResponseEntity with redirect status and location header
69
     */
70
    @Operation(hidden = true)
71
    @GetMapping("${springdoc.swagger-ui.path:/swagger-ui.html}")
72
    public ResponseEntity<Void> redirectToUi(HttpServletRequest request);
73

74
    /**
75
     * Calculates UI root path for WebMVC applications
76
     * Considers servlet context path and MVC servlet path
77
     * @param swaggerUiConfigParameters Configuration parameters to update
78
     * @param sbUrls Additional URL builders for path calculation
79
     */
80
    protected void calculateUiRootPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
81
        StringBuilder... sbUrls);
82

83
    /**
84
     * Builds URLs with context path for WebMVC applications
85
     * @param contextPath Application context path
86
     * @param docsUrl Documentation URL to build
87
     * @return Complete URL with proper context path
88
     */
89
    protected String buildUrl(String contextPath, String docsUrl);
90

91
    /**
92
     * Builds API documentation URL for WebMVC applications
93
     * @param swaggerUiConfigParameters Configuration parameters to update with API docs URL
94
     */
95
    protected void buildApiDocUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);
96

97
    /**
98
     * Builds URL with full context path including path prefix
99
     * @param swaggerUiConfigParameters Configuration parameters
100
     * @param swaggerUiUrl Swagger UI URL to build
101
     * @return Complete URL with context path and prefix
102
     */
103
    protected String buildUrlWithContextPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
104
        String swaggerUiUrl);
105

106
    /**
107
     * Builds Swagger configuration URL for WebMVC applications
108
     * @param swaggerUiConfigParameters Configuration parameters to update with config URL
109
     */
110
    protected void buildSwaggerConfigUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);
111
}
112
```
113

114
### SwaggerWelcomeActuator
115

116
Controller endpoint for Swagger UI integration with Spring Boot Actuator when deployed on management port.
117

118
```java { .api }
119
/**
120
 * Actuator controller endpoint for Swagger UI on management port
121
 * Provides Swagger UI functionality through Spring Boot Actuator infrastructure
122
 */
123
@ControllerEndpoint(id = "swaggerui")
124
public class SwaggerWelcomeActuator extends SwaggerWelcomeCommon {
125
    
126
    /**
127
     * Constructor for actuator-based welcome controller
128
     * @param swaggerUiConfig Swagger UI configuration properties
129
     * @param springDocConfigProperties SpringDoc configuration properties
130
     * @param webEndpointProperties Actuator web endpoint properties for path building
131
     */
132
    public SwaggerWelcomeActuator(SwaggerUiConfigProperties swaggerUiConfig, 
133
        SpringDocConfigProperties springDocConfigProperties, WebEndpointProperties webEndpointProperties);
134

135
    /**
136
     * Redirects to Swagger UI from actuator endpoint
137
     * Handles redirect from management port to Swagger UI interface
138
     * @param request HTTP request for context and path building
139
     * @return ResponseEntity with redirect to Swagger UI
140
     */
141
    @Operation(hidden = true)
142
    @GetMapping("/")
143
    public ResponseEntity<Void> redirectToUi(HttpServletRequest request);
144

145
    /**
146
     * Returns OpenAPI configuration from actuator endpoint
147
     * Serves Swagger UI configuration through management port
148
     * @param request HTTP request for context building
149
     * @return Map containing Swagger UI configuration parameters
150
     */
151
    @Operation(hidden = true)
152
    @GetMapping(value = "/swagger-config", produces = MediaType.APPLICATION_JSON_VALUE)
153
    @ResponseBody
154
    public Map<String, Object> openapiJson(HttpServletRequest request);
155

156
    /**
157
     * Calculates UI root path for actuator deployment
158
     * Uses actuator base path for proper URL building
159
     * @param swaggerUiConfigParameters Configuration parameters to update
160
     * @param sbUrls Additional URL builders
161
     */
162
    protected void calculateUiRootPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
163
        StringBuilder... sbUrls);
164

165
    /**
166
     * Builds API documentation URL for actuator deployment
167
     * @param swaggerUiConfigParameters Configuration parameters to update
168
     */
169
    protected void buildApiDocUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);
170

171
    /**
172
     * Builds URL with context path for actuator deployment
173
     * @param swaggerUiConfigParameters Configuration parameters
174
     * @param swaggerUiUrl URL to build
175
     * @return Complete URL with actuator context path
176
     */
177
    protected String buildUrlWithContextPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
178
        String swaggerUiUrl);
179

180
    /**
181
     * Builds Swagger configuration URL for actuator deployment
182
     * @param swaggerUiConfigParameters Configuration parameters to update
183
     */
184
    protected void buildSwaggerConfigUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);
185
}
186
```
187

188
### SwaggerUiHome
189

190
Controller that provides root path redirect to Swagger UI main page.
191

192
```java { .api }
193
/**
194
 * Controller providing root path redirect to Swagger UI
195
 * Enables accessing Swagger UI from application root when configured
196
 */
197
@Controller
198
public class SwaggerUiHome {
199
    
200
    /**
201
     * Swagger UI path configuration property
202
     */
203
    @Value("${springdoc.swagger-ui.path:/swagger-ui.html}")
204
    private String swaggerUiPath;
205

206
    /**
207
     * MVC servlet path configuration property  
208
     */
209
    @Value("${spring.mvc.servlet.path:}")
210
    private String mvcServletPath;
211

212
    /**
213
     * Redirects root path requests to Swagger UI
214
     * Builds redirect URL considering servlet path and Swagger UI path
215
     * @return Redirect view to Swagger UI main page
216
     */
217
    @GetMapping("/")
218
    @Operation(hidden = true)
219
    public String index();
220
}
221
```
222

223
### SwaggerWelcomeCommon
224

225
Abstract base class providing common functionality for Swagger UI welcome controllers.
226

227
```java { .api }
228
/**
229
 * Abstract base class for Swagger UI welcome controllers
230
 * Provides common URL building and configuration functionality
231
 */
232
public abstract class SwaggerWelcomeCommon extends AbstractSwaggerWelcome {
233
    
234
    /**
235
     * Constructor for common welcome functionality
236
     * @param swaggerUiConfig Swagger UI configuration properties
237
     * @param springDocConfigProperties SpringDoc configuration properties
238
     */
239
    protected SwaggerWelcomeCommon(SwaggerUiConfigProperties swaggerUiConfig, 
240
        SpringDocConfigProperties springDocConfigProperties);
241

242
    /**
243
     * Handles redirect to Swagger UI with query parameter forwarding
244
     * Builds redirect response with proper status and location header
245
     * @param request HTTP request for context and query parameters
246
     * @return ResponseEntity with redirect to Swagger UI
247
     */
248
    protected ResponseEntity<Void> redirectToUi(HttpServletRequest request);
249

250
    /**
251
     * Returns OpenAPI configuration parameters as JSON
252
     * Builds configuration map with URLs and settings for Swagger UI
253
     * @param request HTTP request for context building
254
     * @return Map containing configuration parameters
255
     */
256
    protected Map<String, Object> openapiJson(HttpServletRequest request);
257

258
    /**
259
     * Calculates OAuth2 redirect URL for authentication
260
     * Builds OAuth2 redirect URL if not explicitly configured
261
     * @param swaggerUiConfigParameters Configuration parameters to update
262
     * @param uriComponentsBuilder URI builder for URL construction
263
     */
264
    protected void calculateOauth2RedirectUrl(SwaggerUiConfigParameters swaggerUiConfigParameters, 
265
        UriComponentsBuilder uriComponentsBuilder);
266

267
    /**
268
     * Builds configuration from current request context path
269
     * Updates configuration parameters based on request context
270
     * @param swaggerUiConfigParameters Configuration parameters to update
271
     * @param request HTTP request for context information
272
     */
273
    void buildFromCurrentContextPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
274
        HttpServletRequest request);
275

276
    // Abstract methods implemented by subclasses:
277
    protected abstract void calculateUiRootPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
278
        StringBuilder... sbUrls);
279
    protected abstract void buildApiDocUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);
280
    protected abstract String buildUrlWithContextPath(SwaggerUiConfigParameters swaggerUiConfigParameters, 
281
        String swaggerUiUrl);
282
    protected abstract void buildSwaggerConfigUrl(SwaggerUiConfigParameters swaggerUiConfigParameters);
283
}
284
```
285

286
## HTTP Endpoints
287

288
### Standard Web Application Endpoints
289

290
```java
291
GET ${springdoc.swagger-ui.path:/swagger-ui.html} → SwaggerWelcomeWebMvc.redirectToUi()
292
GET /v3/api-docs/swagger-config → SwaggerConfigResource.openapiJson()
293
GET / (optional)              → SwaggerUiHome.index()
294
```
295

296
### Actuator Management Port Endpoints
297

298
```java
299
GET /actuator/swaggerui/      → SwaggerWelcomeActuator.redirectToUi()
300
GET /actuator/swaggerui/swagger-config → SwaggerWelcomeActuator.openapiJson()
301
```
302

303
## Usage Examples
304

305
### Basic Controller Usage
306

307
Controllers are automatically configured and require no manual setup:
308

309
```java
310
// After application startup, these endpoints are automatically available:
311
// http://localhost:8080/swagger-ui.html (redirects to actual UI)
312
// http://localhost:8080/v3/api-docs/swagger-config (JSON configuration)
313
```
314

315
### Custom Welcome Controller
316

317
Override default behavior with custom controller:
318

319
```java
320
@Controller
321
public class CustomSwaggerWelcome {
322
    
323
    @GetMapping("/api-docs")
324
    public String customRedirect() {
325
        return "redirect:/swagger-ui.html";
326
    }
327
}
328
```
329

330
### Actuator Integration
331

332
Enable Swagger UI on management port:
333

334
```yaml
335
management:
336
  server:
337
    port: 8081
338
springdoc:
339
  use-management-port: true
340
```
341

342
```java
343
// Swagger UI available at:
344
// http://localhost:8081/actuator/swaggerui/
345
```
346

347
### Context Path Handling
348

349
Controllers automatically handle context paths:
350

351
```yaml
352
server:
353
  servlet:
354
    context-path: /myapp
355
spring:
356
  mvc:
357
    servlet:
358
      path: /api
359
```
360

361
```java
362
// Swagger UI automatically available at:
363
// http://localhost:8080/myapp/api/swagger-ui.html
364
```