0
# Auto-Configuration
1

2
Automatic Spring Boot configuration that sets up all necessary components for Swagger UI integration with SpringDoc OpenAPI. The configuration is condition-based and automatically adapts to different deployment scenarios.
3

4
## Capabilities
5

6
### SwaggerConfig
7

8
Main auto-configuration class that creates all necessary beans for Swagger UI functionality.
9

10
```java { .api }
11
/**
12
 * Main Spring Boot auto-configuration class for Swagger UI
13
 * Automatically configures based on properties and runtime conditions
14
 */
15
@Configuration(proxyBeanMethods = false)
16
@ConditionalOnProperty(name = "springdoc.swagger-ui.enabled", matchIfMissing = true)
17
@ConditionalOnWebApplication(type = Type.SERVLET)
18
@ConditionalOnBean(SpringDocConfiguration.class)
19
@Lazy(false)
20
public class SwaggerConfig {
21
    
22
    /**
23
     * Creates SwaggerWelcomeWebMvc bean for standard web applications
24
     * @param swaggerUiConfig Swagger UI configuration properties
25
     * @param springDocConfigProperties SpringDoc configuration properties  
26
     * @param springWebProvider Spring web provider implementation
27
     * @return SwaggerWelcomeWebMvc instance
28
     */
29
    @Bean
30
    @ConditionalOnMissingBean
31
    @ConditionalOnProperty(name = "springdoc.use-management-port", havingValue = "false", matchIfMissing = true)
32
    @Lazy(false)
33
    SwaggerWelcomeWebMvc swaggerWelcome(SwaggerUiConfigProperties swaggerUiConfig, 
34
        SpringDocConfigProperties springDocConfigProperties, SpringWebProvider springWebProvider);
35

36
    /**
37
     * Creates Spring web provider for WebMVC applications
38
     * @return SpringWebMvcProvider instance
39
     */
40
    @Bean
41
    @ConditionalOnMissingBean
42
    @Lazy(false)
43
    public SpringWebProvider springWebProvider() {
44
        return new SpringWebMvcProvider();
45
    }
46

47
    /**
48
     * Creates configuration resource controller for JSON config endpoint
49
     * @param swaggerWelcomeCommon Common welcome functionality
50
     * @return SwaggerConfigResource instance
51
     */
52
    @Bean
53
    @ConditionalOnMissingBean
54
    @ConditionalOnProperty(name = "springdoc.use-management-port", havingValue = "false", matchIfMissing = true)
55
    @Lazy(false)
56
    SwaggerConfigResource swaggerConfigResource(SwaggerWelcomeCommon swaggerWelcomeCommon);
57

58
    /**
59
     * Creates home controller for root path redirects
60
     * @return SwaggerUiHome instance
61
     */
62
    @Bean
63
    @ConditionalOnMissingBean
64
    @ConditionalOnProperty(name = "springdoc.use-root-path", havingValue = "true")
65
    @Lazy(false)
66
    SwaggerUiHome swaggerUiHome();
67

68
    /**
69
     * Creates index page transformer for dynamic configuration injection
70
     * @param swaggerUiConfig Swagger UI configuration
71
     * @param swaggerUiOAuthProperties OAuth configuration
72
     * @param swaggerWelcomeCommon Common welcome functionality
73
     * @param objectMapperProvider JSON object mapper provider
74
     * @return SwaggerIndexTransformer instance
75
     */
76
    @Bean
77
    @ConditionalOnMissingBean
78
    @Lazy(false)
79
    SwaggerIndexTransformer indexPageTransformer(SwaggerUiConfigProperties swaggerUiConfig, 
80
        SwaggerUiOAuthProperties swaggerUiOAuthProperties, SwaggerWelcomeCommon swaggerWelcomeCommon, 
81
        ObjectMapperProvider objectMapperProvider);
82

83
    /**
84
     * Creates Web MVC configurer for resource handling
85
     * @param swaggerUiConfigProperties Swagger UI configuration
86
     * @param swaggerIndexTransformer Index page transformer
87
     * @param actuatorProvider Optional actuator provider
88
     * @param swaggerResourceResolver Resource resolver for web jars
89
     * @return SwaggerWebMvcConfigurer instance
90
     */
91
    @Bean
92
    @ConditionalOnMissingBean
93
    @Lazy(false)
94
    SwaggerWebMvcConfigurer swaggerWebMvcConfigurer(SwaggerUiConfigProperties swaggerUiConfigProperties,
95
        SwaggerIndexTransformer swaggerIndexTransformer, Optional<ActuatorProvider> actuatorProvider, 
96
        SwaggerResourceResolver swaggerResourceResolver);
97

98
    /**
99
     * Creates resource resolver for Swagger UI web jar assets
100
     * @param swaggerUiConfigProperties Swagger UI configuration
101
     * @return SwaggerResourceResolver instance
102
     */
103
    @Bean
104
    @ConditionalOnMissingBean
105
    @Lazy(false)
106
    SwaggerResourceResolver swaggerResourceResolver(SwaggerUiConfigProperties swaggerUiConfigProperties);
107
}
108
```
109

110
### Actuator Configuration
111

112
Nested configuration class for Spring Boot Actuator integration when management port is enabled.
113

114
```java { .api }
115
/**
116
 * Actuator-specific configuration for Swagger UI on management port
117
 * Only active when management port is different from main application port
118
 */
119
@ConditionalOnProperty("springdoc.use-management-port")
120
@ConditionalOnClass(WebMvcEndpointHandlerMapping.class)
121
@ConditionalOnManagementPort(ManagementPortType.DIFFERENT)
122
static class SwaggerActuatorWelcomeConfiguration {
123

124
    /**
125
     * Creates actuator welcome controller for management port deployment
126
     * @param swaggerUiConfig Swagger UI configuration
127
     * @param springDocConfigProperties SpringDoc configuration
128
     * @param webEndpointProperties Actuator web endpoint properties
129
     * @return SwaggerWelcomeActuator instance
130
     */
131
    @Bean
132
    @ConditionalOnMissingBean
133
    @Lazy(false)
134
    SwaggerWelcomeActuator swaggerActuatorWelcome(SwaggerUiConfigProperties swaggerUiConfig, 
135
        SpringDocConfigProperties springDocConfigProperties, WebEndpointProperties webEndpointProperties);
136
}
137
```
138

139
## Configuration Conditions
140

141
### Property-Based Conditions
142

143
```java { .api }
144
// Enables/disables Swagger UI entirely
145
@ConditionalOnProperty(name = "springdoc.swagger-ui.enabled", matchIfMissing = true)
146

147
// Controls whether to use management port for Swagger UI
148
@ConditionalOnProperty(name = "springdoc.use-management-port", havingValue = "false", matchIfMissing = true)
149

150
// Enables root path redirect to Swagger UI
151
@ConditionalOnProperty(name = "springdoc.use-root-path", havingValue = "true")
152

153
// Enables actuator-specific configuration
154
@ConditionalOnProperty("springdoc.use-management-port")
155
```
156

157
### Environment-Based Conditions
158

159
```java { .api }
160
// Only activates for servlet-based web applications
161
@ConditionalOnWebApplication(type = Type.SERVLET)
162

163
// Requires SpringDoc core configuration to be present
164
@ConditionalOnBean(SpringDocConfiguration.class)
165

166
// Only when Spring Boot Actuator WebMVC is available
167
@ConditionalOnClass(WebMvcEndpointHandlerMapping.class)
168

169
// Only when management port is different from main port
170
@ConditionalOnManagementPort(ManagementPortType.DIFFERENT)
171

172
// Prevents duplicate bean creation
173
@ConditionalOnMissingBean
174
```
175

176
## Bean Dependencies
177

178
The auto-configuration creates beans with specific dependency relationships:
179

180
```java
181
SwaggerConfig
182
├── swaggerWelcome() → SwaggerWelcomeWebMvc
183
│   ├── SwaggerUiConfigProperties (injected)
184
│   ├── SpringDocConfigProperties (injected)
185
│   └── SpringWebProvider (from springWebProvider())
186
├── springWebProvider() → SpringWebMvcProvider
187
├── swaggerConfigResource() → SwaggerConfigResource
188
│   └── SwaggerWelcomeCommon (base class dependency)
189
├── swaggerUiHome() → SwaggerUiHome
190
├── indexPageTransformer() → SwaggerIndexPageTransformer
191
│   ├── SwaggerUiConfigProperties (injected)
192
│   ├── SwaggerUiOAuthProperties (injected)
193
│   ├── SwaggerWelcomeCommon (injected)
194
│   └── ObjectMapperProvider (injected)
195
├── swaggerWebMvcConfigurer() → SwaggerWebMvcConfigurer
196
│   ├── SwaggerUiConfigProperties (injected)
197
│   ├── SwaggerIndexTransformer (from indexPageTransformer())
198
│   ├── Optional<ActuatorProvider> (injected)
199
│   └── SwaggerResourceResolver (from swaggerResourceResolver())
200
└── swaggerResourceResolver() → SwaggerResourceResolver
201
    └── SwaggerUiConfigProperties (injected)
202
```
203

204
## Usage Examples
205

206
### Basic Auto-Configuration
207

208
Most applications require no additional configuration:
209

210
```java
211
@SpringBootApplication
212
public class Application {
213
    public static void main(String[] args) {
214
        SpringApplication.run(Application.class, args);
215
    }
216
}
217
```
218

219
### Custom Configuration Override
220

221
Override specific beans when customization is needed:
222

223
```java
224
@Configuration
225
public class CustomSwaggerConfig {
226
    
227
    @Bean
228
    @Primary
229
    public SwaggerWelcomeWebMvc customSwaggerWelcome(
230
        SwaggerUiConfigProperties swaggerUiConfig,
231
        SpringDocConfigProperties springDocConfigProperties, 
232
        SpringWebProvider springWebProvider) {
233
        // Custom implementation
234
        return new CustomSwaggerWelcomeWebMvc(swaggerUiConfig, springDocConfigProperties, springWebProvider);
235
    }
236
}
237
```
238

239
### Conditional Bean Registration
240

241
Register additional beans based on configuration:
242

243
```java
244
@Configuration
245
@ConditionalOnProperty("app.swagger.custom-theme")
246
public class CustomThemeConfig {
247
    
248
    @Bean
249
    public SwaggerIndexTransformer customThemeTransformer() {
250
        return new CustomThemeIndexTransformer();
251
    }
252
}
253
```
254

255
## Configuration Properties Integration
256

257
The auto-configuration integrates with Spring Boot's configuration property system:
258

259
```yaml
260
springdoc:
261
  swagger-ui:
262
    enabled: true  # Controls @ConditionalOnProperty
263
    path: /swagger-ui.html
264
  use-management-port: false  # Controls actuator configuration
265
  use-root-path: false  # Controls SwaggerUiHome creation
266
  
267
management:
268
  server:
269
    port: 8081  # Triggers actuator-specific configuration when different from server.port
270
```