升级springdoc-openapi-ui至1.6.7+后API UI无法显示的问题排查

版本升级后的变化 #

springdoc-openapi-ui从1.6.7版本开始，升级了其依赖的swagger-core组件版本，其中对io.swagger.core.v3:swagger-annotations的最低要求提升至2.2.0。这个版本新增了io.swagger.v3.oas.annotations.media.PatternProperties类，而你的项目中通过io.confluent:kafka-schema-registry-client间接引入了旧版本的swagger-annotations:2.1.10，该版本中不存在这个类，导致运行时触发NoClassDefFoundError，进而引发API UI访问的500内部错误。

解决方案 #

方案1：显式声明高版本的swagger-annotations依赖 #

在项目的pom.xml中直接添加高版本的swagger-annotations依赖，强制覆盖间接引入的旧版本：

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.15</version> <!-- 选择与springdoc 1.6.7+兼容的2.2.x系列版本 -->
</dependency>

方案2：排除springdoc依赖中的旧swagger-annotations #

也可以在springdoc-openapi-ui的依赖配置中排除自带的swagger-annotations，确保项目使用你指定的高版本：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.7</version> <!-- 替换为你要升级的目标版本 -->
    <exclusions>
        <exclusion>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
    </exclusions>
</dependency>

添加后同样需要显式声明高版本的swagger-annotations依赖（同方案1）。

验证步骤 #

执行以下命令确认依赖版本是否替换成功：

mvn dependency:tree | grep swagger-annotations

确认输出的版本为2.2.0及以上后，重启项目即可正常访问API UI。

内容的提问来源于stack exchange，提问作者Michal Špondr