Spring Boot集成springdoc-openapi-ui启动报swagger-ui路径映射错误

云上老周

2026-10-3

错误根因

该报错核心原因为springdoc-openapi-ui版本与当前项目的Spring Boot版本不兼容：你使用的1.5.2版本springdoc仅适配Spring Boot 2.4/2.5版本，若项目使用Spring Boot 2.6及以上版本，框架默认的路径匹配规则变更就会触发该路径校验报错。

解决方案

根据你使用的Spring Boot版本选择对应方案即可：

场景1：项目使用Spring Boot 2.6.x ~ 2.7.x版本

方案一：升级springdoc版本到适配2.x分支的最新稳定版1.6.15，修改Maven依赖即可：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.15</version>
</dependency>

方案二：若不需要升级springdoc版本，可在项目配置文件中添加配置，兼容旧版路径匹配规则：
若使用application.properties：
```
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
```
若使用application.yml：
```
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher
```

场景2：项目使用Spring Boot 3.x版本

1.x分支的springdoc完全不兼容Spring Boot 3.x，需要替换为适配3.x的2.x分支依赖：

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

注意：springdoc 2.x分支最低要求Java 17，若你要保留Java 11版本，请降级Spring Boot到2.7.x版本，使用场景1的方案。