SpringDoc集成后Swagger UI始终显示petshop示例API如何解决

Swagger UI 固定展示petshop示例API，核心是UI没有成功拉取到当前项目生成的OpenAPI接口描述，触发了内置演示数据的兜底逻辑，常见触发原因：

• 依赖版本不兼容：你引入的springdoc-openapi-ui:1.6.9和springdoc-openapi-webmvc-core:1.2.32版本跨度极大，属于跨大版本的不匹配组合，会直接导致项目自身的OpenAPI描述端点/v3/api-docs无法正常注册，UI拉取不到接口定义时就会加载内置的petshop演示数据。
• 拦截规则未放行：如果项目配置了权限拦截、静态资源拦截，把OpenAPI描述端点、Swagger UI相关资源路径拦截，同样会导致UI拉取数据失败，回退到演示数据。

1. 修正依赖版本 #

删除版本不匹配的依赖，使用同版本配套的依赖组合，Gradle配置参考：

// 仅保留同版本的ui依赖即可，webmvc-core会通过传递依赖自动引入同版本，无需手动声明
api "org.springdoc:springdoc-openapi-ui:1.6.9"

注意：所有springdoc相关的组件依赖必须保持版本号完全一致，禁止跨大版本混合引用，否则会出现端点失效、配置不加载等各类异常。

2. 放行相关路径 #

如果项目集成了Spring Security、Shiro等权限框架，或自定义了Web拦截规则，需要将以下路径加入白名单放行：

• /v3/api-docs/**
• /swagger-ui/**
• /swagger-resources/**
  无自定义拦截逻辑可跳过此步骤。

3. 确认配置扫描范围 #

检查你的OpenApiConfig类是否在Spring组件扫描范围内：配置类所在包需要和Spring Boot启动类所在包同级，或处于启动类@ComponentScan注解指定的扫描路径下。配置类未被扫描只会导致文档标题、描述等元信息不生效，不会触发petshop演示数据展示，该步骤仅用于校验自定义文档信息是否正常加载。

4. 强制指定接口描述地址（可选兜底配置） #

完成上述步骤后如果仍有异常，可以在application配置文件中强制指定Swagger UI拉取接口描述的地址，application.yml配置示例：

springdoc:
  swagger-ui:
    url: /v3/api-docs

重启项目后先直接访问http://127.0.0.1:11014/v3/api-docs，如果返回的是当前项目的接口JSON结构，说明接口描述端点正常工作，此时访问Swagger UI地址就会展示项目自身的接口，不会再出现petshop演示数据。

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