SpringBoot集成Swagger后无法本地运行Swagger UI的问题求助

环境配置 #

1. Swagger依赖 #

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

2. Spring Security配置 #

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) {
        try {
            return http
                    .requestMatchers(HttpMethod.POST,
                                "/api/users/register", "/api/users/login").permitAll()
                    .requestMatchers(HttpMethod.GET, "/swagger-ui/**").permitAll()
                    .requestMatchers(HttpMethod.GET, "/api/users/{id}").hasRole("USER")
                    .requestMatchers(HttpMethod.PUT, "/api/users/{id}").hasRole("USER")
                    .requestMatchers(HttpMethod.DELETE, "/api/users/{id}").hasRole("USER")
                    .requestMatchers(HttpMethod.POST, "/api/transactions").hasRole("USER")
                    .requestMatchers(HttpMethod.GET, "/api/transactions/{id}").hasRole("USER")
                    .requestMatchers(HttpMethod.PUT, "/api/transactions/{id}").hasRole("USER")
                    .requestMatchers(HttpMethod.DELETE, "/api/transactions/{id}").hasRole("USER")
                    .build();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}

3. application.properties配置 #

spring.application.name=Fintech-Backend-Developer-Assignment
springdoc.api-docs.path=/api-docs
spring.h2.console.enabled=true
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=password
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect

问题描述 #

访问http://localhost:8080/swagger-ui/index.html时，出现403 Forbidden错误，无权限访问页面。

问题原因 #

1. 仅放行GET方法的/swagger-ui/**，但Swagger UI加载过程中会使用OPTIONS等其他HTTP方法请求资源。
2. 未放行API文档路径/api-docs（对应配置的springdoc.api-docs.path），以及springdoc默认的/v3/api-docs/**路径，导致页面无法加载API元数据。

修复方案 #

修改Security配置，放行所有Swagger相关路径的所有请求方法：

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) {
    try {
        return http
                .authorizeHttpRequests(auth -> auth
                        // 放行注册、登录接口
                        .requestMatchers(HttpMethod.POST, "/api/users/register", "/api/users/login").permitAll()
                        // 放行所有Swagger相关路径的所有请求方法
                        .requestMatchers("/swagger-ui/**", "/api-docs/**", "/v3/api-docs/**").permitAll()
                        // 用户相关接口权限控制
                        .requestMatchers(HttpMethod.GET, "/api/users/{id}").hasRole("USER")
                        .requestMatchers(HttpMethod.PUT, "/api/users/{id}").hasRole("USER")
                        .requestMatchers(HttpMethod.DELETE, "/api/users/{id}").hasRole("USER")
                        // 交易相关接口权限控制
                        .requestMatchers(HttpMethod.POST, "/api/transactions").hasRole("USER")
                        .requestMatchers(HttpMethod.GET, "/api/transactions/{id}").hasRole("USER")
                        .requestMatchers(HttpMethod.PUT, "/api/transactions/{id}").hasRole("USER")
                        .requestMatchers(HttpMethod.DELETE, "/api/transactions/{id}").hasRole("USER")
                        // 其余所有请求需认证
                        .anyRequest().authenticated()
                )
                .build();
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

额外检查 #

1. 版本兼容性：springdoc 2.0.x适配SpringBoot 3.x，若使用SpringBoot 2.x需切换到springdoc 1.x版本。
2. 清除浏览器缓存后重新访问Swagger UI页面。

内容的提问来源于stack exchange，提问作者Umair