Spring Boot 2.7.6集成Swagger失败问题排查求助

使用Spring Boot 2.7.6集成springfox-boot-starter 3.0.0配置Swagger时遇到以下问题：

• 访问http://localhost:8081/my-api-web/v2/api-docs可获取JSON，但控制台抛出Unable to find a model that matches key ModelKey{qualifiedModelName=ModelName{namespace='java.lang', name='Void'}, ...}错误
• 访问Swagger UI（https://localhost:8081/my-api-web/swagger-ui/ 或 http://localhost:8081/my-api-web/swagger-ui/index.html）失败，后者返回404，同时控制台出现Invalid character found in method name异常

现有配置信息 #

pom.xml依赖 #

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

配置属性 #

server.servlet.context-path=/my-api-web
server.port=8081

Swagger配置类 #

@Configuration
public class SwaggerConfig implements WebMvcConfigurer {

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

    @Override
    public void addResourceHandlers(final ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/swagger-ui.html");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

Spring Security配置类 #

@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    public void configure(final WebSecurity web) throws Exception {
        web.ignoring().antMatchers("/v2/api-docs", "/configuration/**", "/swagger*/**", "/webjars/**")
                .antMatchers(HttpMethod.OPTIONS, "/**");
    }

    @Override
    protected void configure(final HttpSecurity http) throws Exception {

        // configure provider and filter
        http.requestMatchers().antMatchers("/enpoint1/**", "/endpoint2/**").and()
                .authenticationProvider(this.preAuthenticatedAuthenticationProvider())
                .addFilter(this.userContextFilter());

        // configure what is authenticated and what is anonymous
        http.authorizeRequests().antMatchers("/endpoint1/**", "/endpoint2/**").authenticated() //
                .antMatchers("/**", "/v2/api-docs", "/configuration/**", "/swagger*/**", "/webjars/**").permitAll() //
                .anyRequest().permitAll();

        http.csrf().disable();

        http.exceptionHandling().authenticationEntryPoint(this.authenticationEntryPoint());
    }

    ...
}

1. 修正Swagger UI访问方式与资源映射 #

• HTTPS请求异常原因：控制台的Invalid character found in method name异常是因为用https://访问了未配置SSL的HTTP端口（8081），改用http://localhost:8081/my-api-web/swagger-ui/访问即可。
• 移除手动资源映射：Springfox 3.0.0的starter已经自动配置了Swagger UI的资源映射，不需要在SwaggerConfig中手动实现addResourceHandlers方法，直接删除该方法即可。若需保留，需修正资源路径为classpath:/META-INF/resources/（而非具体文件路径）。

2. 解决Void模型找不到的错误 #

该错误是因为接口返回Void类型时Springfox无法正确映射，可通过以下方式解决：
修改Docket配置，添加ignoredParameterTypes(Void.class)忽略Void类型：

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

也可将返回Void的接口改为返回ResponseEntity<Void>或其他具体类型。

3. 优化Spring Security配置 #

当前requestMatchers的范围会导致后续authorizeRequests只对/enpoint1/**、/endpoint2/**生效，Swagger相关路径的放行规则无法被应用。调整配置顺序：

@Override
protected void configure(final HttpSecurity http) throws Exception {
    // 先配置所有路径的安全规则
    http.authorizeRequests()
            .antMatchers("/endpoint1/**", "/endpoint2/**").authenticated()
            .antMatchers("/v2/api-docs", "/configuration/**", "/swagger*/**", "/webjars/**").permitAll()
            .anyRequest().permitAll();

    // 再配置provider和filter，仅对指定路径生效
    http.requestMatchers().antMatchers("/enpoint1/**", "/endpoint2/**")
            .and()
            .authenticationProvider(this.preAuthenticatedAuthenticationProvider())
            .addFilter(this.userContextFilter());

    http.csrf().disable();
    http.exceptionHandling().authenticationEntryPoint(this.authenticationEntryPoint());
}

同时保留WebSecurity中的ignoring配置，确保Swagger资源不被安全过滤器拦截。

完全可以用springdoc-openapi-ui作为Swagger的替代方案，且更适合Spring Boot 2.6+版本：

• 兼容性更好：Springfox对Spring Boot 2.6+存在诸多兼容性问题，springdoc-openapi是专门为Spring Boot设计的OpenAPI实现，完美适配新版本。
• 配置更简单：无需编写复杂配置类，添加依赖即可自动生成API文档。
• 基于OpenAPI 3：支持OpenAPI 3.0规范，功能更丰富。
• 访问路径：默认访问路径为http://localhost:8081/my-api-web/swagger-ui.html。

依赖配置如下：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version> <!-- 适配Spring Boot 2.7.x的版本 -->
</dependency>

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