springdoc-openapi v2.6.0无法显示Swagger-UI问题求助

使用版本 #

• spring-boot-starter-parent: 3.3.3
• java.version: 21
• spring-cloud-version: 2023.0.3
• springdoc-openapi-starter-webmvc-ui: 2.6.0

现象 #

启动应用后访问/swagger-ui/index.html，未返回Swagger UI页面，而是收到如下JSON响应：

{"name":"swagger-ui","profiles":["index.html"],"label":null,"version":"d2592f45c32657d214294f6b030bef6003d0ee6d","state":null,"propertySources":[]}

相关代码示例 #

REST端点代码：

@RestController
@RequestMapping("/test/api/web-client")
public class WebClientResource {

    @GetMapping("/greet")
    public String greet() {
        return "Hello World!";
    }
}

依赖配置（pom.xml） #

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-config-server</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-config-client</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.6.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

引入的spring-cloud-config-server依赖会创建匹配/{name}/{profiles}的路由规则，当访问/swagger-ui/index.html时，该路由会将swagger-ui识别为配置名称（name），index.html识别为配置环境（profiles），因此返回了配置相关的JSON响应，覆盖了Swagger UI的静态资源请求。

方案1：修改Swagger UI访问路径 #

在配置文件（application.yml/application.properties）中指定Swagger UI的自定义路径，避开Config Server的路由匹配：

springdoc:
  swagger-ui:
    path: /swagger-ui-custom.html

修改后访问新路径即可正常打开Swagger UI页面。

方案2：给Config Server添加路由前缀 #

为Spring Cloud Config Server设置专属前缀，让其仅处理特定路径下的请求：

spring:
  cloud:
    config:
      server:
        prefix: /config

配置后Config Server只会响应/config开头的请求，不会拦截Swagger UI的路径。

方案3：移除/禁用Config Server（若无需该功能） #

如果项目不需要作为Config Server使用，直接移除spring-cloud-config-server依赖即可；若需保留依赖但禁用Config Server功能，可在启动类中排除其自动配置：

@SpringBootApplication(exclude = {ConfigServerAutoConfiguration.class})
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}

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