Spring Webflux函数式端点集成SpringDoc生成OpenAPI为空如何解决？

可行性说明 #

Spring Webflux 函数式端点完全支持通过 SpringDoc 自动生成 OpenAPI 定义，你遇到的paths为空的问题，是因为函数式端点不会像注解式控制器（@RestController）一样被自动扫描，需要额外增加专属的注解配置。

正确配置步骤 #

1. 确认依赖引入 #

首先确保你引入了适配 Webflux 函数式端点的 SpringDoc 依赖，Maven 配置示例如下：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-functional</artifactId>
    <version>最新稳定版本</version>
</dependency>

Gradle 配置示例：

implementation 'org.springdoc:springdoc-openapi-starter-webflux-functional:最新稳定版本'

2. 给RouterFunction Bean添加OpenAPI注解 #

SpringDoc 依靠@RouterOperation注解识别函数式端点的定义，你需要在路由方法上添加该注解并补全接口元信息，调整后的代码示例如下：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springdoc.core.annotations.RouterOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestMethod;
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 static org.springframework.web.reactive.function.server.RequestPredicates.POST;
import static org.springframework.web.reactive.function.server.RequestPredicates.accept;

@Configuration(proxyBeanMethods = false)
public class Routers {

    @Bean
    @RouterOperation(
        path = "/api/upload",
        method = RequestMethod.POST,
        consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
        operation = @Operation(
            summary = "文件上传接口",
            description = "接收 multipart 格式的文件并完成存储",
            requestBody = @RequestBody(
                required = true,
                content = @Content(
                    mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
                    // 替换为你自定义的上传参数实体类
                    schema = @Schema(implementation = UploadFileDTO.class)
                )
            ),
            responses = {
                @ApiResponse(responseCode = "200", description = "文件上传成功"),
                @ApiResponse(responseCode = "400", description = "请求参数不合法"),
                @ApiResponse(responseCode = "500", description = "服务内部错误")
            }
        )
    )
    public RouterFunction<ServerResponse> uploadRoute(UploadHandler uploadHandler) {
        return RouterFunctions
                .route(POST("/api/upload").and(accept(MediaType.MULTIPART_FORM_DATA)), uploadHandler::handleUploadedFiles);
    }
}

如果单个RouterFunction Bean 中定义了多个路由规则，可以使用@RouterOperations注解包裹多个@RouterOperation进行配置。

3. 补充参数实体类注解（可选） #

你可以在自定义的上传参数实体类中添加@Schema注解补充字段说明，示例如下：

import io.swagger.v3.oas.annotations.media.Schema;
import org.springframework.web.multipart.MultipartFile;

@Schema(description = "文件上传请求参数")
public class UploadFileDTO {
    @Schema(description = "上传的文件", requiredMode = Schema.RequiredMode.REQUIRED)
    private MultipartFile file;
    @Schema(description = "文件所属分类", example = "avatar")
    private String category;

    // 省略getter、setter
}

4. 自定义全局OpenAPI信息（可选） #

如果需要修改生成的OpenAPI全局标题、版本、描述等信息，可以注册自定义OpenAPI Bean：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
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("文件上传服务API文档")
                        .version("1.0.0")
                        .description("基于Spring Webflux函数式端点开发的文件上传服务接口说明"));
    }
}

验证效果 #

配置完成后启动服务，访问/v3/api-docs即可获取完整的OpenAPI定义，访问/swagger-ui.html可查看可视化的接口文档界面。

内容的提问来源于stack exchange，提问作者Stefan K.