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
    @Email
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