Resolving Swagger UI Access Issues in Spring Boot 3

Migrating from Spring Boot 2 to Spring Boot 3 brings many improvements and changes, particularly in how security configurations are handled. This migration can sometimes lead to unexpected behavior, especially when integrating components like Swagger UI with Spring Security. A common issue faced during such upgrades is the inaccessibility of Swagger UI due to security constraints that weren’t previously an issue in Spring Boot 2. This blog post will address how to resolve these issues, ensuring that Swagger UI remains accessible while keeping the rest of your API secured.

Understanding the Issue

With the upgrade to Spring Boot 3, all requests including those to the Swagger UI might require authentication due to changes in the default security configurations and the way Spring Security is set up. The objective here is to allow unrestricted access to Swagger UI for API documentation purposes, while securing other API endpoints.

The Dependency Setup

First, ensure your pom.xml is configured with the necessary Spring Boot and Swagger dependencies:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.1.4</version>
</parent>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

Configuring Spring Security

Adjustments in Spring Security Configuration

In Spring Boot 3, some annotations and their behaviors have changed. Notably, @EnableWebSecurity no longer includes the @Configuration annotation implicitly. This means that any class annotated with @EnableWebSecurity should also explicitly be annotated with @Configuration to be recognized by Spring as a configuration class. Here’s how you can adjust your security configurations:

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html")
                .permitAll()
                .anyRequest().authenticated()
            )
            .httpBasic();  // Assuming basic authentication is adequate

        return http.build();
    }
}

Explanation of Changes

• CSRF Protection: Disabled CSRF protection for simplicity, especially when dealing with non-browser clients that interact with the API.
• Permit Swagger: Specifically permits all requests to paths associated with Swagger documentation.
• Secure Other Requests: Ensures all other requests are authenticated.
• Basic Authentication: Utilizes basic authentication for simplicity, though other more secure methods should be considered for production environments.

When upgrading to Spring Boot 3, it’s crucial to revisit and possibly revise your security configurations to accommodate changes in the underlying framework. By explicitly configuring access rules for Swagger UI and ensuring that @Configuration is used alongside @EnableWebSecurity, you can maintain both the accessibility of your API documentation and the security of your API endpoints.

This approach not only resolves access issues post-upgrade but also aligns with best practices for securing applications developed with Spring Boot. Always ensure to test security configurations thoroughly to avoid exposing sensitive API endpoints inadvertently.