Spring MVC配置默认映射后无法打开springdoc-openapi的Swagger-ui

云原生阿岚

2026-8-9

解决Spring MVC中@GetMapping("**")与Swagger UI冲突的问题

问题场景

当Spring MVC应用中存在带有@GetMapping("**")的默认映射方法时，springdoc-openapi的Swagger UI（http://localhost:8080/swagger-ui.html）无法正常访问。原因是Swagger UI相关的请求会被这个通配符映射拦截，无法到达Swagger的处理控制器。

示例冲突代码：

@Controller
class HelloController {
    @GetMapping("**")
    fun notFound(): ModelAndView {
       return ModelAndView()
    }
}

使用版本：

spring-boot: 2.7.6
springdoc-openapi-ui: 1.6.13

解决方案

以下两种方法均可在保留通用错误页面映射的同时，正常访问Swagger UI：

方法1：排除Swagger相关路径

修改默认映射的注解，排除Swagger UI及API文档的所有相关路径，确保这些请求不会被通配符映射拦截：

@Controller
class HelloController {
    @RequestMapping(
        method = [RequestMethod.GET],
        value = ["**"],
        excludes = [
            "/swagger-ui/**",
            "/v3/api-docs/**",
            "/swagger-resources/**",
            "/webjars/swagger-ui/**"
        ]
    )
    fun notFound(): ModelAndView {
        return ModelAndView() // 返回你的通用错误页面视图
    }
}

方法2：调整控制器优先级

给默认映射控制器设置最低优先级，让Swagger的内置控制器（默认优先级更高）先匹配处理相关请求：

import org.springframework.core.Ordered
import org.springframework.core.annotation.Order
import org.springframework.stereotype.Controller
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.servlet.ModelAndView

@Controller
@Order(Ordered.LOWEST_PRECEDENCE)
class HelloController {
    @GetMapping("**")
    fun notFound(): ModelAndView {
        return ModelAndView() // 返回你的通用错误页面视图
    }
}