Spring Boot集成Swagger UI遇500错误：Schema.requiredMode()方法缺失

问题描述 #

使用springdoc-openapi-starter-webmvc-ui:2.1.0集成Swagger UI，访问/swagger-ui/index.html时触发500错误，核心报错信息为：

java.lang.NoSuchMethodError: 'io.swagger.v3.oas.annotations.media.Schema$RequiredMode io.swagger.v3.oas.annotations.media.Schema.requiredMode()'

原因分析 #

该错误由依赖版本冲突引发：项目中存在旧版本的io.swagger.core.v3注解包（swagger-annotations或openapi-annotations），而springdoc-openapi-starter-webmvc-ui:2.1.0依赖的新版本注解包中新增了Schema.requiredMode()方法，旧版本无此方法，导致方法查找失败。

解决方案 #

1. 排查依赖冲突 #

执行命令查看项目依赖树定位冲突包：

• Maven项目：

  mvn dependency:tree | grep io.swagger.core.v3
  

• Gradle项目：

  gradle dependencies | grep io.swagger.core.v3
  

2. 排除冲突依赖 #

在springdoc-openapi-starter-webmvc-ui依赖中排除旧版本注解包：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>openapi-annotations</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3. 显式引入兼容注解包 #

添加与springdoc-openapi-starter-webmvc-ui:2.1.0匹配的新版本注解包（2.1.0对应openapi-core版本为2.2.10）：

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>openapi-annotations</artifactId>
    <version>2.2.10</version>
</dependency>

4. 验证修复 #

清理项目重新构建，保持原有SpringdocConfig配置类和application.yaml配置不变，再次访问/swagger-ui/index.html即可正常查看接口文档。

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