Secure Swagger UI in Spring Boot with Spring Security – A Step‑by‑Step Guide

Introduction

Swagger2 provides convenient API documentation for Spring Boot projects, but by default it has no access control, which can expose internal APIs when the service is reachable from the internet. By adding Spring Security, the Swagger UI can be protected with authentication while the rest of the application continues to work as before.

Adding Required Dependencies

Include the following Maven dependencies in pom.xml:

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

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

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

Configuring Application Properties

Define a default user for Spring Security in application.properties (or application.yml):

spring.security.user.name=admin
spring.security.user.password=admin

When the application starts, any request will be redirected to Spring Security’s login page, using the credentials defined above.

Swagger Configuration Class

Create a configuration class for Swagger2:

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.secbro.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 2.x Integration with Swagger")
                .description("User Management API 1.0 Documentation")
                .termsOfServiceUrl("http://www.choupangxia.com/")
                .version("1.0")
                .contact(new Contact("程序新视界", "http://www.choupangxia.com/", "[email protected]"))
                .build();
    }
}

Spring Security Configuration

Define a security configuration that protects the Swagger UI but leaves the business APIs untouched:

@EnableWebSecurity
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                .antMatchers("/api/**").permitAll() // business APIs are handled elsewhere
                .anyRequest().authenticated()
                .and()
                .formLogin()
                .permitAll();
    }
}

The antMatchers("/api/**").permitAll() line excludes existing business endpoints from Spring Security, ensuring that only the Swagger UI (and its static resources) requires authentication.

Result

After restarting the application, accessing http://localhost:8080/swagger-ui.html triggers the Spring Security login page (as shown below). Once logged in with the configured credentials, the Swagger UI becomes visible, while all other requests continue to operate normally.

Conclusion

Integrating Spring Security with Swagger2 allows fine‑grained access control for API documentation without disrupting existing business APIs. The same approach can be reversed to expose Swagger publicly while securing other endpoints, simply by adjusting the antMatchers rules and ensuring static Swagger resources are excluded from security filters.