0
# SpringDoc OpenAPI
1
2
SpringDoc OpenAPI is a Java library that automates the generation of OpenAPI 3 documentation for Spring Boot applications. It examines applications at runtime to infer API semantics from Spring configurations, class structures, and annotations, generating comprehensive REST API documentation in JSON/YAML and HTML formats with integrated Swagger UI.
3
4
## Package Information
5
6
- **Package Name**: org.springdoc:springdoc-openapi
7
- **Package Type**: Maven
8
- **Language**: Java 17+
9
- **Installation**: Add starter dependency to Maven `pom.xml`:
10
11
**For Spring Web MVC with Swagger UI:**
12
```xml
13
<dependency>
14
<groupId>org.springdoc</groupId>
15
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
16
<version>2.8.6</version>
17
</dependency>
18
```
19
20
**For Spring WebFlux with Swagger UI:**
21
```xml
22
<dependency>
23
<groupId>org.springdoc</groupId>
24
<artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
25
<version>2.8.6</version>
26
</dependency>
27
```
28
29
**For API documentation only (no UI):**
30
```xml
31
<dependency>
32
<groupId>org.springdoc</groupId>
33
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
34
<version>2.8.6</version>
35
</dependency>
36
```
37
38
For Gradle:
39
```gradle
40
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.6'
41
```
42
43
## Core Imports
44
45
```java
46
import io.swagger.v3.oas.annotations.Operation;
47
import io.swagger.v3.oas.annotations.Parameter;
48
import io.swagger.v3.oas.annotations.responses.ApiResponse;
49
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
50
import io.swagger.v3.oas.annotations.tags.Tag;
51
import org.springdoc.core.configuration.SpringDocConfiguration;
52
import org.springdoc.core.properties.SpringDocConfigProperties;
53
import org.springdoc.core.properties.SwaggerUiConfigProperties;
54
```
55
56
## Basic Usage
57
58
SpringDoc works automatically with zero configuration for basic Spring Boot REST applications:
59
60
```java
61
@SpringBootApplication
62
public class ApiApplication {
63
public static void main(String[] args) {
64
SpringApplication.run(ApiApplication.class, args);
65
}
66
}
67
68
@RestController
69
@Tag(name = "User Management", description = "Operations for managing users")
70
public class UserController {
71
72
@GetMapping("/users")
73
@Operation(summary = "Get all users", description = "Retrieves a list of all users")
74
@ApiResponse(responseCode = "200", description = "Users retrieved successfully")
75
public List<User> getAllUsers() {
76
return userService.findAll();
77
}
78
79
@PostMapping("/users")
80
@Operation(summary = "Create user")
81
public ResponseEntity<User> createUser(
82
@Parameter(description = "User to create") @RequestBody User user) {
83
User created = userService.save(user);
84
return ResponseEntity.status(201).body(created);
85
}
86
87
@GetMapping("/users/{id}")
88
@Operation(summary = "Get user by ID")
89
public ResponseEntity<User> getUserById(
90
@Parameter(description = "User ID") @PathVariable Long id) {
91
return userService.findById(id)
92
.map(ResponseEntity::ok)
93
.orElse(ResponseEntity.notFound().build());
94
}
95
}
96
```
97
98
Once the application starts, documentation is automatically available at:
99
- `http://localhost:8080/swagger-ui/index.html` - Interactive Swagger UI interface
100
- `http://localhost:8080/v3/api-docs` - OpenAPI JSON specification
101
- `http://localhost:8080/v3/api-docs.yaml` - OpenAPI YAML specification
102
103
## Architecture
104
105
SpringDoc OpenAPI operates through several integrated components:
106
107
- **Runtime Analysis**: Scans Spring Boot applications at startup to discover REST endpoints
108
- **Annotation Processing**: Interprets Swagger/OpenAPI annotations and Spring web annotations
109
- **Schema Generation**: Automatically generates JSON schemas from Java classes and validation annotations
110
- **Document Assembly**: Combines discovered APIs into complete OpenAPI specifications
111
- **UI Integration**: Provides Swagger UI with dynamic configuration and real-time API exploration
112
- **Multi-Format Output**: Supports JSON, YAML, and HTML documentation formats
113
114
## Capabilities
115
116
### Automatic API Documentation Generation
117
118
Core functionality that discovers Spring REST endpoints and generates OpenAPI specifications without manual configuration.
119
120
```java { .api }
121
@Configuration
122
@ConditionalOnProperty(name = "springdoc.api-docs.enabled", matchIfMissing = true)
123
public class SpringDocConfiguration {
124
@Bean
125
OpenApiResource openApiResource(OpenAPI openAPI, SpringDocConfigProperties springDocConfigProperties,
126
OperationService operationService, RequestMappingInfoHandlerMapping requestMappingInfoHandlerMapping,
127
Optional<ActuatorProvider> actuatorProvider);
128
129
@Bean
130
OperationService operationService(GenericParameterService genericParameterService,
131
List<OperationCustomizer> operationCustomizers, PropertyResolverUtils propertyResolverUtils,
132
SpringDocConfigProperties springDocConfigProperties);
133
}
134
135
@ConfigurationProperties("springdoc")
136
public class SpringDocConfigProperties {
137
private String apiDocsPath = "/v3/api-docs";
138
private boolean enabled = true;
139
private String packagesToScan;
140
private String pathsToMatch;
141
private String packagesToExclude;
142
private String pathsToExclude;
143
}
144
145
@RestController
146
public class OpenApiResource {
147
public String openapiJson(HttpServletRequest request, Locale locale) throws JsonProcessingException;
148
public String openapiYaml(HttpServletRequest request, Locale locale) throws JsonProcessingException;
149
}
150
```
151
152
[Core API Generation](./core-api-generation.md)
153
154
### Swagger UI Integration
155
156
Automatic integration with Swagger UI for interactive API documentation and testing.
157
158
```java { .api }
159
@Configuration
160
@ConditionalOnProperty(name = "springdoc.swagger-ui.enabled", matchIfMissing = true)
161
@ConditionalOnWebApplication(type = Type.SERVLET)
162
public class SwaggerConfig {
163
// Swagger UI configuration and resource handling
164
}
165
166
@ConfigurationProperties("springdoc.swagger-ui")
167
public class SwaggerUiConfigProperties {
168
private String path = "/swagger-ui.html";
169
private boolean enabled = true;
170
private String configUrl;
171
private String url;
172
private String[] urls;
173
}
174
```
175
176
[Swagger UI Configuration](./web-configuration.md)
177
178
### Spring Security Integration
179
180
Automatic detection and documentation of Spring Security configurations, including OAuth2 and JWT authentication.
181
182
```java { .api }
183
@Configuration
184
@ConditionalOnClass(SecurityScheme.class)
185
public class SpringDocSecurityConfiguration {
186
// Security schema detection and documentation
187
}
188
189
@ConfigurationProperties("springdoc.swagger-ui.oauth")
190
public class SwaggerUiOAuthProperties {
191
private String clientId;
192
private String clientSecret;
193
private String realm;
194
private String appName;
195
private String scopeSeparator;
196
private String[] scopes;
197
}
198
```
199
200
### WebFlux Support
201
202
Full support for Spring WebFlux reactive applications with functional routing.
203
204
```java { .api }
205
@Configuration
206
@ConditionalOnWebApplication(type = Type.REACTIVE)
207
public class SpringDocWebFluxConfiguration {
208
// WebFlux-specific configuration
209
}
210
211
@RouterOperation(operation = @Operation(summary = "Get user by ID"))
212
public RouterFunction<ServerResponse> userRoutes() {
213
return route()
214
.GET("/users/{id}", this::getUserById)
215
.build();
216
}
217
```
218
219
### Validation Integration
220
221
Automatic schema generation from Bean Validation (JSR-303) annotations.
222
223
```java { .api }
224
public class User {
225
@NotNull
226
@Size(min = 1, max = 50)
227
private String username;
228
229
230
private String email;
231
232
@Min(18)
233
@Max(120)
234
private Integer age;
235
}
236
```
237
238
### Actuator Integration
239
240
Integration with Spring Boot Actuator for management endpoints and health checks.
241
242
```java { .api }
243
@ControllerEndpoint(id = "swaggerui")
244
public class SwaggerWelcomeActuator {
245
public ResponseEntity<Void> redirectToUi(HttpServletRequest request);
246
public Map<String, Object> openapiJson(HttpServletRequest request);
247
}
248
```
249
250
[Actuator Integration](./controllers.md)
251
252
### Auto-Configuration
253
254
Comprehensive Spring Boot auto-configuration that adapts to different application types and deployment scenarios.
255
256
```java { .api }
257
@Configuration
258
@ConditionalOnWebApplication
259
@ConditionalOnBean(SpringDocConfiguration.class)
260
public class SwaggerConfig {
261
@Bean
262
SwaggerWelcomeWebMvc swaggerWelcome(SwaggerUiConfigProperties swaggerUiConfig,
263
SpringDocConfigProperties springDocConfigProperties, SpringWebProvider springWebProvider);
264
265
@Bean
266
SwaggerConfigResource swaggerConfigResource(SwaggerWelcomeCommon swaggerWelcomeCommon);
267
268
@Bean
269
SwaggerIndexTransformer indexPageTransformer(SwaggerUiConfigProperties swaggerUiConfig,
270
SwaggerUiOAuthProperties swaggerUiOAuthProperties, SwaggerWelcomeCommon swaggerWelcomeCommon,
271
ObjectMapperProvider objectMapperProvider);
272
}
273
```
274
275
[Auto-Configuration Details](./auto-configuration.md)
276
277
### Resource Processing
278
279
Dynamic resource transformation and web jar management for Swagger UI assets.
280
281
```java { .api }
282
public class SwaggerIndexPageTransformer extends AbstractSwaggerIndexTransformer
283
implements SwaggerIndexTransformer {
284
public Resource transform(HttpServletRequest request, Resource resource,
285
ResourceTransformerChain transformerChain) throws IOException;
286
}
287
288
public class SwaggerResourceResolver extends LiteWebJarsResourceResolver {
289
protected String findWebJarResourcePath(String pathStr);
290
}
291
```
292
293
[Resource Processing](./resource-processing.md)
294
295
## Configuration Examples
296
297
### Basic Configuration
298
299
```yaml
300
springdoc:
301
api-docs:
302
path: /v3/api-docs
303
enabled: true
304
swagger-ui:
305
path: /swagger-ui.html
306
enabled: true
307
try-it-out-enabled: true
308
operations-sorter: method
309
tags-sorter: alpha
310
```
311
312
### Advanced Configuration with Security
313
314
```yaml
315
springdoc:
316
api-docs:
317
path: /v3/api-docs
318
swagger-ui:
319
path: /swagger-ui.html
320
oauth:
321
client-id: my-client-id
322
client-secret: my-client-secret
323
realm: my-realm
324
scopes: read,write
325
packages-to-scan: com.example.api
326
paths-to-match: /api/**
327
```
328
329
### Production Configuration
330
331
```yaml
332
springdoc:
333
api-docs:
334
enabled: true
335
swagger-ui:
336
enabled: false # Disable UI in production
337
show-actuator: false
338
use-management-port: true
339
340
management:
341
server:
342
port: 8081
343
endpoints:
344
web:
345
base-path: /actuator
346
```
347
348
## Supported Features
349
350
### Spring Boot 3.x Support
351
- Java 17+ and Jakarta EE 9 namespace
352
- Native GraalVM image compilation support
353
- Spring Boot 3.x auto-configuration patterns
354
355
### OpenAPI 3.0 Specification
356
- Complete OpenAPI 3.0.3 specification support
357
- JSON and YAML output formats
358
- Schema generation from Java types
359
- Complex type relationships and inheritance
360
361
### Validation Integration
362
- JSR-303 Bean Validation annotation support
363
- Automatic constraint documentation (@NotNull, @Size, @Pattern, etc.)
364
- Custom validation annotation support
365
366
### Advanced Features
367
- Multiple OpenAPI group support for microservices
368
- Custom schema and example generation
369
- Internationalization (i18n) support
370
- Custom Swagger UI themes and branding
371
372
## Error Handling
373
374
SpringDoc provides comprehensive error handling for common deployment scenarios:
375
376
- **Missing Dependencies**: Clear error messages for missing Swagger UI or core dependencies
377
- **Configuration Conflicts**: Validation and warnings for conflicting property settings
378
- **Path Conflicts**: Detection and resolution of conflicting URL patterns
379
- **Security Issues**: Proper handling of security contexts and authentication flows
380
- **Performance Optimization**: Lazy loading and caching strategies for large APIs