Swagger with Spring Boot 3

Problem Statement

Integrating Swagger with Spring Boot 3 presents unique challenges due to the transition from Java EE (javax) to Jakarta EE (jakarta) APIs. Many developers encounter 404 errors when trying to access the Swagger UI, especially when using older projects with Spring Boot 2.x dependencies like Springfox.

Common symptoms include:

• Whitelabel error pages (404) when accessing standard Swagger URLs
• Compatibility issues with Spring Boot 3's Jakarta EE 9+ baseline
• Conflicting dependencies that prevent proper initialization
• Security configurations blocking Swagger endpoints

Solution Overview

Use springdoc-openapi instead of Springfox. Springdoc's v2+ supports Jakarta EE and Spring Boot 3 natively. Key benefits include:

• Automatic generation of OpenAPI 3 specifications
• Built-in Swagger UI integration
• Support for Spring Security, JWT, and OAuth 2

Maven Configuration

Replace Springfox dependencies with springdoc-openapi in your pom.xml:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version> <!-- Use latest stable version -->
</dependency>

WARNING

Remove any existing Springfox dependencies like springfox-boot-starter to avoid conflicts.

Gradle Configuration

For Gradle projects, add to build.gradle:

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'

Accessing Swagger UI

After adding the dependency:

• OpenAPI JSON: http://localhost:8080/v3/api-docs
• Swagger UI: http://localhost:8080/swagger-ui/index.html

Note

Springdoc automatically redirects /swagger-ui.html to /swagger-ui/index.html

Spring Security Configuration

If you're using Spring Security, explicitly permit access to Swagger endpoints:

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(
                    "/v3/api-docs/**",
                    "/swagger-ui/**",
                    "/swagger-ui.html"
                ).permitAll()
                .anyRequest().authenticated()
            );
        return http.build();
    }
}

Customizing OpenAPI Metadata

Create an OpenApiConfig.java to customize API information and security schemes:

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "My API",
        version = "1.0",
        description = "API Documentation",
        contact = @Contact(name = "Support", url = "https://example.com")
    ),
    security = {@SecurityRequirement(name = "bearerToken")}
)
@SecuritySchemes({
    @SecurityScheme(name = "bearerToken", 
                   type = SecuritySchemeType.HTTP, 
                   scheme = "bearer", 
                   bearerFormat = "JWT")
})
public class OpenApiConfig {}

Configuring Properties

Additional settings in application.properties:

# Change base Swagger UI path
springdoc.swagger-ui.path=/custom-api-docs

# Disable OpenAPI (if needed)
#springdoc.api-docs.enabled=false

# Package scanning
springdoc.packages-to-scan=com.example.api

Troubleshooting Guide

Common issues and solutions:

1. Cached Dependencies (IntelliJ)

Symptoms: Old dependencies persist after changes
Solution: Invalidate caches:

1. File → Invalidate Caches → Invalidate and Restart
2. Run mvn clean install -DskipTests

2. Conflicting Dependencies

Symptoms: ClassNotFound or initialization errors
Solution: Check dependencies:

mvn dependency:tree

Remove any conflicting artifacts like:

• Springfox (io.springfox)
• Older springdoc releases (<2.0.0)

3. Whitelabel 404 Persists

Possible causes:

• Missing permissions in Spring Security
• Context-path mismatch (use server.servlet.context-path in properties)
• Old dependencies not fully removed
• Custom configurations blocking swagger

Best Practices

1. Pin versions: Always specify exact versions in POM/Gradle
2. Security: Never expose Swagger in production
3. Documentation Lifecycle: Integrate openapi generation in CI/CD pipelines
4. Version Alignment: Check springdoc.org for version compatibility

Conclusion

For Spring Boot 3+, springdoc-openapi provides a modern, compatible implementation for Swagger integration. By replacing Springfox dependencies, configuring security permissions, and leveraging springdoc's Jakarta EE 9 support, you can generate comprehensive API documentation with minimal configuration.

Upgrade Tip: For existing Spring Boot 2.x projects, migrate to springdoc before upgrading to Spring Boot 3 to avoid compatibility issues.