Spring Boot 3 – Configure Spring Security to Allow Swagger UI

1. Overview

In this tutorial, we’ll learn how to configure Spring Security to allow access to Swagger UI in a Spring Boot 3 application.

Swagger UI is a tool for documenting APIs. It provides a user-friendly interface to interact with the API and test endpoints. However, when we enable Spring Security in our application, the Swagger UI becomes inaccessible due to security restrictions.

We’ll explore how to set up Swagger in a Spring Boot 3 application and configure Spring Security to allow access to the Swagger UI.

2. Code Setup

Let’s start by setting up our application. We’ll add the necessary dependencies and create a simple controller. We’ll configure Swagger and test that the Swagger UI isn’t accessible. Then we’ll fix it by configuring Spring Security.

2.1. Add Swagger and Spring Security Dependencies

First, we’ll add the necessary dependencies to the pom.xml file:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

The springdoc-openapi-starter-webmvc-ui is a Springdoc OpenAPI library that encapsulates Swagger. It contains the required dependencies and annotations to set up Swagger in the application.

The spring-boot-starter-security dependency provides Spring Security for the application. When we add this dependency, Spring Security is enabled by default and blocks access to all URLs.

The spring-boot-starter-web dependency is required to create APIs.

2.2. Controller

Next, let’s create a controller that has an endpoint:

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

When we call the hello endpoint, it returns the string “Hello, World!”.

3. Configure Swagger

Next, let’s configure Swagger. We’ll set up the configuration to enable Swagger and add annotations to the controller.

3.1. Configuration Class

To configure Swagger, we need to create a configuration class:

@Configuration
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/**")
            .build();
    }
}

Here, we’ve created a SwaggerConfig class and defined a publicApi() method that returns a GroupedOpenApi bean. This bean groups all the endpoints that match the specified path pattern.

We’ve defined a group public in the method and specified the path pattern as “/**”. This means that all the endpoints in the application will be included in this group.

3.2. Swagger Annotations

Next, let’s add Swagger annotations to the controller:

@Operation(summary = "Returns a Hello World message")
@GetMapping("/hello")
public String hello() {
    return "Hello, World!";
} 

We added the @Operation annotation to the hello() method to describe the endpoint. This description will be displayed in the Swagger UI.

3.3. Testing

Now, let’s run the application and test the Swagger UI. By default, the Swagger UI should be accessible at http://localhost:8080/swagger-ui/index.html:

In the above image, we can see that the Swagger UI isn’t accessible. Instead, we’re prompted to enter the username and password. Spring Security wants to authenticate the user before allowing access to the URL.

4. Configure Spring Security to Allow Swagger UI

Now, let’s configure Spring Security to allow access to the Swagger UI. We’ll look at two ways to achieve this: using SecurityFilterChain and WebSecurityCustomizer.

4.1. Using WebSecurityCustomizer

An easy way to exclude paths from Spring Security is by using the WebSecurityCustomizer interface. We can disable Spring Security on specified URLs using this interface.

Let’s define a bean of type WebSecurityCustomizer in a configuration class:

@Configuration 
public class SecurityConfig {
   @Bean
    public WebSecurityCustomizer webSecurityCustomizer() {
        return (web) -> web.ignoring()
          .requestMatchers("/swagger-ui/**", "/v3/api-docs*/**");
    }
}

The @Configuration annotation marks the class as a configuration class. Next, we define a bean of type WebSecurityCustomizer.

Here, we’ve used a lambda expression to define a WebSecurityCustomizer implementation. We’ve used the ignoring() method to exclude the Swagger UI URLs /swagger-ui/** and /v3/api-docs*/** from the security configuration.

This is useful when we want to ignore all security rules on a URL. It’s only recommended if the URL is internal and not public exposed as no security rules will apply to it. 

4.2. Using SecurityFilterChain

Another way to override Spring Security’s default implementation is to define a SecurityFilterChain bean. Then we can allow Swagger URLs in the implementation we provide.

For this, we can define a SecurityFilterChain bean:

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(
      authorizeRequests -> authorizeRequests.requestMatchers("/swagger-ui/**")
        .permitAll()
        .requestMatchers("/v3/api-docs*/**")
        .permitAll());

    return http.build();
}

This method configures the security filter chain to allow access to the Swagger UI URLs:

• We’ve used the authorizeHttpRequests() method to define the authorization rules.
• The requestMatchers() method is used to match the URLs. We’ve specified the Swagger UI URL patterns /swagger-ui/** and /v3/api-docs*/**.
• /swagger-ui/** is the URL pattern for the Swagger UI while /v3/api-docs*/** is the URL pattern for the OpenAPI documentation that Swagger calls to fetch the API information.
• We’ve used the permitAll() method to allow access to these URLs without authentication.
• And finally, we’ve returned the http.build() method to build the security filter chain.

This is the recommended approach to allow unauthenticated requests to certain URL patterns. These URLs will have Spring Security headers in the response. However, they won’t need user authentication.

4.3. Testing

Now, let’s run the application and test the Swagger UI again. The Swagger UI should be accessible now.

As we can see the page is accessible and contains information about our controller endpoint.

5. Conclusion

In this article, we learned how to configure Spring Security to allow access to the Swagger UI in a Spring Boot 3 application. We explored how to exclude the Swagger UI URL from the Spring Security configuration using the SecurityFilterChain and WebSecurityCustomizer interfaces.