webflux整合swagger教程

相信已经有不少人上手了 webflux，包括我之前也写了很多类似的整合教程，但是在整合 swagger 框架方面，我还是第一次尝试。

webflux 和 springmvc 不同，webflux 返回的 Mono、Flux 不能被 swagger
框架正常识别。因此我们要引入 springfox-spring-webflux，否则的话需要写很多的适配代码，才能让 swagger 兼容
Mono、Flux。

下面我们一起开始本次教程的整合之旅，我这里的 swagger 版本是 3.0.0，2.10.x 版本的也可以整合，具体看你个人兴趣和你使用的
spring-boot-starter-webflux 版本。

1.首先是 pom.xml 中的代码。

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
        <version>2.1.0.RELEASE</version>
    </dependency>
    
    <!--数据库开始-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-mongodb</artifactId>
        <version>2.1.0.RELEASE</version>
    </dependency>
    <!--数据库结束-->
	<!--整合swagger开始-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-spring-webflux</artifactId>
        <version>3.0.0</version>
        <exclusions>
            <exclusion>
                <groupId>org.springframework.plugin</groupId>
                <artifactId>spring-plugin-core</artifactId>
            </exclusion>
            <exclusion>
                <groupId>org.springframework.plugin</groupId>
                <artifactId>spring-plugin-metadata</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>3.0.0</version>
        <exclusions>
            <exclusion>
                <groupId>org.springframework.plugin</groupId>
                <artifactId>spring-plugin-core</artifactId>
            </exclusion>
            <exclusion>
                <groupId>org.springframework.plugin</groupId>
                <artifactId>spring-plugin-metadata</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>3.0.0</version>
    </dependency>
	<!--整合swagger结束-->
	<!--引入更高版本开始-->
    <dependency>
        <groupId>org.springframework.plugin</groupId>
        <artifactId>spring-plugin-core</artifactId>
        <version>2.0.0.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.plugin</groupId>
        <artifactId>spring-plugin-metadata</artifactId>
        <version>2.0.0.RELEASE</version>
    </dependency>
    <!--引入更高版本结束-->
</dependencies>

pom 中引入 springfox-spring-webflux 后，我们需要把 spring-plugin-core
排除掉，否则会启动报错，抛出下面类似的异常。

ERROR 2368 --- [           main] o.s.b.d.LoggingFailureAnalysisReporter   : 
 
***************************
APPLICATION FAILED TO START
***************************
 
Description:
 
An attempt was made to call a method that does not exist. The attempt was made from the following location:
 
    springfox.documentation.spring.web.plugins.DocumentationPluginsManager.createContextBuilder(DocumentationPluginsManager.java:154)
 
The following method did not exist:
 
    org.springframework.plugin.core.PluginRegistry.getPluginOrDefaultFor(Ljava/lang/Object;Lorg/springframework/plugin/core/Plugin;)Lorg/springframework/plugin/core/Plugin;
 
The method's class, org.springframework.plugin.core.PluginRegistry, is available from the following locations:
 
    jar:file:/C:/work/maven/mymaven/repo/org/springframework/plugin/spring-plugin-core/1.2.0.RELEASE/spring-plugin-core-1.2.0.RELEASE.jar!/org/springframework/plugin/core/PluginRegistry.class
 
It was loaded from the following location:
 
    file:/C:/work/maven/mymaven/repo/org/springframework/plugin/spring-plugin-core/1.2.0.RELEASE/spring-plugin-core-1.2.0.RELEASE.jar
 
 
Action:
 
Correct the classpath of your application so that it contains a single, compatible version of org.springframework.plugin.core.PluginRegistry

为了解决这个问题，我们需要引入更高版本的 spring-plugin-core，就是上面 pom.xml 中最下面的两个依赖项。

做完第一步之后，我们现在需要开启 swagger，网上很多人使用的是 @EnableSwagger2WebFlux
注解，那是因为他们使用的是快照版本，现在的正式版本已经把它废弃掉了 @Deprecated，推荐的还是使用 @EnableSwagger2。

@Configuration
@EnableSwagger2
public class SwaggerWebFluxConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(new ApiInfoBuilder()
                    .description("gxf project")
                    .title("gxf RESTful APIs")
                    .termsOfServiceUrl("https://www.gxf.com/")
                    .contact(new Contact("gxf", "https://www.gxf.com/", "1333335@qq.com"))
                    .version("1.0.0")
                    .build())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.gxf.webflux.demo"))
            .paths(PathSelectors.any())
            .build()
            .genericModelSubstitutes(Optional.class, Flux.class, Mono.class);
    }
}

做完这一步之后，还不行。如果你直接运行项目，访问 swagger，会出现 404。网上很多人说需要开启 @EnableWebFlux
注解，这一步其实是多余的，加上了也还是 404。

@EnableWebFlux
@SpringBootApplication
@ComponentScan(basePackages = {"com.xttblog.webflux.demo"},
        excludeFilters = @ComponentScan.Filter(type = FilterType.ASSIGNABLE_TYPE,
                classes = {}))
public class XttblogApplication {

    public static void main(String[] args) {
        SpringApplication.run(XttblogApplication.class, args);
    }
}

一番搜索后，我在官网上看到了 WebFluxConfigurer，通过配置实现 WebFluxConfigurer 后，可以完美解决
webflux 整合 swagger 出现 404 问题。

@Configuration
public class SwaggerUiWebFluxConfigurer implements WebFluxConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        // 配置跨域
        registry.addMapping("/**").allowedOrigins("*").allowedMethods("GET", "POST", "OPTION", "DELETE").maxAge(3600);
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 重新映射路径
        registry.
                addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
                .resourceChain(false);

        registry.addResourceHandler("/swagger-ui.html**")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/").resourceChain(true);
    }
}

网上有很多野代码，都是基于 3.0 的快照版本，根本就无法解决 404 问题，包括 stackoverflow 的回答。

因为 3.0.0 的正式版本中，访问路径是 http://localhost:8080/swagger-ui/index.html，且这些
swagger 资源是放在
classpath:/META-INF/resources/webjars/springfox-swagger-ui/
下面的，很多回答是把资源放在 classpath:/META-INF/resources/ 下，并且映射的是
swagger-ui.html。这是低版本的 swagger 的做法，正式版本和快照版本还是有很大差别的，官网上修复了很多 bug。

做完上面的工作后，启动项目，最终实现 weblux 和 swagger3 的整合，推荐使用正式版本的
springfox-spring-webflux。