Spring Boot 3 OpenAPI/Swagger Integration

Problem Statement

When adding OpenAPI documentation to a Spring Boot 3 application, you might encounter a 404 Not Found error when trying to access /swagger-ui.html. This commonly occurs when incorrect dependencies are used or compatibility rules are violated. The core issues include:

• Using outdated dependencies incompatible with Spring Boot 3
• Incorrect security configurations blocking access to endpoints
• Missing annotations or misconfigured paths
• Compatibility mismatches between Spring Boot versions and OpenAPI libraries

Solutions

1. Use the Correct Dependency

Spring Boot 3 requires springdoc-openapi-starter-webmvc-ui instead of the legacy springdoc-openapi-ui. Replace your dependency:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version> <!-- Match version with Spring Boot -->
</dependency>

COMPATIBILITY MATRIX

Select the springdoc version based on your Spring Boot version:

Spring Boot	Springdoc Version
3.1.x	2.1.x - 2.2.x
3.0.x	2.0.x
2.7.x	1.6.x+
2.6.x	1.6.x+

Reference: Official Compatibility Matrix

2. Add Required Annotations

Annotate your main application class with @OpenAPIDefinition:

@SpringBootApplication
@OpenAPIDefinition // Required for springdoc detection
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

3. Configure Spring Security (If Applicable)

If you use Spring Security, exclude Swagger endpoints from authentication:

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

4. Custom Configuration (Optional)

For custom OpenAPI configuration, implement WebMvcConfigurer:

@OpenAPIDefinition
@Configuration
public class SwaggerConfig implements WebMvcConfigurer {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .servers(List.of(
                new Server().url("http://localhost:8080").description("Local")
            ))
            .info(new Info()
                .title("API Documentation")
                .version("1.0")
            );
    }
}

5. Reactive Application Setup (WebFlux)

For Spring WebFlux applications, use the WebFlux UI starter:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.1.0</version>
</dependency>

Access endpoints:

• OpenAPI JSON: /v3/api-docs
• Swagger UI: /swagger-ui.html

6. Manual Path Configuration

If endpoints aren't exposed, configure paths in application.yml:

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    enabled: true
  api-docs:
    path: /v3/api-docs

Kotlin-Specific Configuration

Kotlin projects require an additional Jackson dependency:

<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-kotlin</artifactId>
    <version>2.15.0</version>
</dependency>

Troubleshooting Tips

1. Clear browser cookies if you previously accessed incorrect endpoints
2. Verify the swagger-ui.html endpoint matches your configuration
3. Check startup logs for springdoc initialization messages
4. For Jakarta EE compatibility issues, ensure all Java EE dependencies are migrated to Jakarta EE 9+

TIP

After implementing these steps, your Swagger UI will be accessible at:
http://localhost:8080/swagger-ui.html
OpenAPI JSON at: http://localhost:8080/v3/api-docs