自定义Swagger UI端点无法访问，请求返回404问题求助

1. 解决/v3/api-docs无内容问题（RouterFunction适配） #

WebFlux的RouterFunction不会被springdoc自动扫描，必须手动为路由添加OpenAPI元数据，可通过以下两种方式实现：

方式一：为Handler方法添加Swagger注解 #

在请求处理类的方法上标注OpenAPI相关注解，示例：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;

@Operation(summary = "获取用户详情", description = "根据用户ID查询用户信息")
@ApiResponse(responseCode = "200", description = "成功返回用户数据",
             content = @Content(schema = @Schema(implementation = User.class)))
public Mono<User> getUser(@Parameter(description = "目标用户ID") @PathVariable String id) {
    // 业务逻辑实现
}

方式二：手动注册RouterFunction的OpenAPI配置 #

创建配置类，通过OpenApiCustomizer手动定义API元数据，示例：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.PathItem;
import io.swagger.v3.oas.models.Paths;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.customizers.OpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("WebFlux API文档").version("1.0"))
                .paths(new Paths()
                        .addPathItem("/api/users/{id}", new PathItem()
                                .get(new io.swagger.v3.oas.models.Operation()
                                        .summary("获取用户详情")
                                        .description("根据ID查询用户")
                                        .addParametersItem(new io.swagger.v3.oas.models.parameters.Parameter()
                                                .name("id")
                                                .in("path")
                                                .required(true)
                                                .description("用户ID"))
                                        .addResponsesItem("200", new io.swagger.v3.oas.models.Response()
                                                .description("成功响应")
                                                .content(new io.swagger.v3.oas.models.media.Content()
                                                        .addMediaType("application/json", new io.swagger.v3.oas.models.media.MediaType()
                                                                .schema(new io.swagger.v3.oas.models.media.Schema<User>().$ref("#/components/schemas/User")))))));
    }
}

2. 解决Swagger UI 404问题 #

检查依赖版本兼容性 #

Spring Boot 4.0.x需搭配springdoc-openapi-starter-webflux-ui 2.5.0及以上版本，确认依赖配置：
Maven示例：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.5.0</version>
</dependency>

Gradle示例：

implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.5.0'

调整Swagger UI路径配置 #

WebFlux环境下Swagger UI默认端点为/swagger-ui.html，若自定义路径出现404，可修改配置：

springdoc:
  swagger-ui:
    path: /swagger-ui.html  # 改用默认HTML端点避免路径冲突

或保留原配置，添加路由重定向规则：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.RouterFunctions;
import org.springframework.web.reactive.function.server.ServerResponse;
import java.net.URI;

@Configuration
public class SwaggerRouterConfig {
    @Bean
    public RouterFunction<ServerResponse> swaggerRouter() {
        return RouterFunctions.route()
                .GET("/swagger-ui", req -> ServerResponse.temporaryRedirect(URI.create("/swagger-ui.html")).build())
                .build();
    }
}

排除Swagger端点被自定义路由拦截 #

若自定义RouterFunction包含全局路径匹配（如/**），需排除Swagger相关端点：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.RouterFunctions;
import org.springframework.web.reactive.function.server.ServerResponse;

@Configuration
public class AppRouterConfig {
    @Bean
    public RouterFunction<ServerResponse> appRoutes(YourHandler handler) {
        return RouterFunctions.route()
                // 业务路由配置
                .GET("/api/users", handler::listUsers)
                // 排除Swagger相关路径，交由springdoc处理
                .path("/v3/api-docs", this::skipSwaggerRoutes)
                .path("/swagger-ui", this::skipSwaggerRoutes)
                .build();
    }

    private RouterFunction<ServerResponse> skipSwaggerRoutes() {
        return RouterFunctions.route()
                .GET("/**", req -> ServerResponse.notFound().build())
                .build();
    }
}

3. 验证配置 #

重启应用后：

• 访问http://localhost:8080/v3/api-docs，确认返回JSON格式的API文档
• 访问配置的Swagger UI端点，确认页面正常加载

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