求Spring Webflux环境下用Swagger描述WebService并生成客户端存根的方案

当然有成熟的解决方案啦！在Spring WebFlux场景下，Springdoc OpenAPI是目前最靠谱的选择——它完美适配反应式编程模型，能无缝集成Swagger/OpenAPI生态，帮你搞定API文档自动生成，还能导出规范文件来生成客户端存根。下面一步步给你讲清楚怎么做：

一、先把Springdoc OpenAPI集成到WebFlux项目里 #

首先得在项目里添加依赖，Maven和Gradle的配置分别是这样：

Maven依赖 #

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.2.0</version> <!-- 记得用最新的稳定版本哦 -->
</dependency>

Gradle依赖 #

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

然后简单配置一下，比如在application.yml里加这些：

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs  # 这里是OpenAPI规范文件的访问路径
  swagger-ui:
    enabled: true
    path: /swagger-ui.html  # 可视化文档页面的路径

启动项目后，访问/swagger-ui.html就能看到漂亮的可视化API文档，而/v3/api-docs会输出OpenAPI 3.0格式的JSON文件——这就是我们生成客户端存根的核心依据。

二、用OpenAPI Generator生成客户端存根 #

有了OpenAPI规范文件，接下来用OpenAPI Generator来自动生成WebFlux风格的客户端存根，它支持多种语言和框架，对Java Spring的支持特别友好。

方式1：用Maven插件自动生成 #

直接在pom.xml里添加插件配置，这样打包项目的时候就能自动生成客户端代码：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.6.0</version> <!-- 选最新稳定版 -->
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <!-- 可以填本地的规范文件路径，也可以填远程的API地址比如http://localhost:8080/v3/api-docs -->
                <inputSpec>${project.basedir}/src/main/resources/openapi.json</inputSpec>
                <generatorName>spring</generatorName> <!-- 指定生成Spring风格的代码 -->
                <configOptions>
                    <library>webflux</library> <!-- 明确生成WebFlux客户端 -->
                    <basePackage>com.yourcompany.client</basePackage> <!-- 客户端代码的基础包名 -->
                    <apiPackage>com.yourcompany.client.api</apiPackage> <!-- API接口的包名 -->
                    <modelPackage>com.yourcompany.client.model</modelPackage> <!-- 模型类的包名 -->
                    <reactive>true</reactive> <!-- 开启反应式支持 -->
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

执行mvn clean install之后，插件就会自动把生成的客户端代码放到项目里，直接就能用。

方式2：用命令行工具生成 #

如果不想用Maven插件，也可以直接用OpenAPI Generator的命令行工具，比如：

openapi-generator generate \
  -i http://localhost:8080/v3/api-docs \
  -g spring \
  --library webflux \
  -o ./client-stub \
  --package-name com.yourcompany.client

这个命令会从你的WebFlux项目拉取最新的API规范，然后在./client-stub目录下生成客户端代码，你可以把这些代码复制到你的客户端项目里。

三、使用生成的客户端存根 #

生成的代码已经封装好了WebClient的调用逻辑，你只需要简单配置一下服务地址，然后注入API接口就能用了：

先写个配置类：

@Configuration
public class ClientConfig {
    @Bean
    public ApiClient apiClient() {
        ApiClient apiClient = new ApiClient();
        // 设置你的WebService地址
        apiClient.setBasePath("http://your-service-host:8080");
        // 还可以配置超时、拦截器这些
        apiClient.setWebClient(apiClient.getWebClient().mutate()
                .clientConnector(new ReactorClientHttpConnector(HttpClient.create().responseTimeout(Duration.ofSeconds(10))))
                .build());
        return apiClient;
    }
}

然后在业务类里注入对应的API接口就行：

@Service
public class BusinessService {
    private final UserApi userApi;

    // 构造方法注入
    public BusinessService(UserApi userApi) {
        this.userApi = userApi;
    }

    public Mono<User> getUserInfo(Long userId) {
        // 直接调用生成的API方法，返回Mono，完美适配WebFlux
        return userApi.getUserById(userId);
    }
}

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