spring cloud gateway 集成swagger2

前言

我们都知道springcloud的gateway没有采用传统的阻塞式的springMVC框架，为了提升网关的性能，SpringCloud Gateway是基于WebFlux框架实现的，而WebFlux框架底层则使用了高性能的Reactor模式通信框架Netty，所有的请求都是异步非阻塞式的请求。而对于WebFlux框架，swagger2集成与传统的阻塞式MVC框架集成有所不同，且swagger版本低于3.0根本就不支持web Flux框架。

集成

1、maven依赖

<dependency>
                <groupId>io.springfoxgroupId>
                <artifactId>springfox-boot-starterartifactId>
                <version>3.0.0version>
                <exclusions>
                    <exclusion>
                        <groupId>org.springframework.plugingroupId>
                        <artifactId>spring-plugin-metadataartifactId>
                    exclusion>
                    <exclusion>
                        <groupId>org.springframework.plugingroupId>
                        <artifactId>spring-plugin-coreartifactId>
                    exclusion>
                exclusions>
dependency>
<dependency>
                <groupId>org.springframework.plugingroupId>
                <artifactId>spring-plugin-coreartifactId>
                <version>2.0.0.RELEASEversion>
dependency>
            
<dependency>
                <groupId>org.springframework.plugingroupId>
                <artifactId>spring-plugin-metadataartifactId>
                <version>2.0.0.RELEASEversion>
dependency>

这里要特别注意一点，添加springfox-boot-starter的3.0.0的依赖的时候，一定要排除spring-plugin-core和spring-plugin-metadata，原因是springfox-boot-starter对于上面的两个依赖所使用的是1.2.0版本，当在gateway项目中运行的时候会提示类找不到，查阅资料后发现需要使用其上两个插件的2.0版本的依赖，报错如下

2021-09-21 00:48:41.547 [main] DEBUG o.s.b.diagnostics.LoggingFailureAnalysisReporter - Application failed to start due to an exception
java.lang.NoSuchMethodError: org.springframework.plugin.core.PluginRegistry.getPluginFor(Ljava/lang/Object;)Ljava/util/Optional;
	at springfox.documentation.schema.plugins.SchemaPluginsManager.viewProvider(SchemaPluginsManager.java:95)
	at springfox.documentation.spring.web.readers.operation.OperationModelsProvider.viewForReturn(OperationModelsProvider.java:116)
	at springfox.documentation.spring.web.readers.operation.OperationModelsProvider.collectFromReturnType(OperationModelsProvider.java:85)
	at springfox.documentation.spring.web.readers.operation.OperationModelsProvider.apply(OperationModelsProvider.java:58)
	at springfox.documentation.spring.web.plugins.DocumentationPluginsManager.modelContexts(DocumentationPluginsManager.java:160)
	at springfox.documentation.spring.web.scanners.ApiModelReader.read(ApiModelReader.java:87)
	at springfox.documentation.spring.web.scanners.ApiListingScanner.scan(ApiListingScanner.java:154)
	at springfox.documentation.spring.web.scanners.ApiDocumentationScanner.scan(ApiDocumentationScanner.java:67)
	at springfox.documentation.spring.web.plugins.AbstractDocumentationPluginsBootstrapper.scanDocumentation(AbstractDocumentationPluginsBootstrapper.java:96)
	at springfox.documentation.spring.web.plugins.AbstractDocumentationPluginsBootstrapper.bootstrapDocumentationPlugins(AbstractDocumentationPluginsBootstrapper.java:82)
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.start(DocumentationPluginsBootstrapper.java:100)
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:182)
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:53)
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:360)
	at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:158)
	at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:122)
	at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:895)
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:554)
	at org.springframework.boot.web.reactive.context.ReactiveWebServerApplicationContext.refresh(ReactiveWebServerApplicationContext.java:62)
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:758)
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:750)
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:405)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:315)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1237)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1226)

2、配置Swagger Config

新建一个配置类SwaggerConfig.java，（类名随意），内容如下

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui/index.html
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("网关Api")
                .description("网关Api描述")
                .termsOfServiceUrl("https://127.0.0.1:8080/")
                .contact(new Contact("author", "url", "email"))
                .version("1.0")
                .build();
    }
}

然后在启动类上增加@EnableSwagger2注解

3、开发

接下来根据业务需求进行开发即可

遇到的问题

1、不能推断出base URL

访问页面的时候，弹窗内容如下：

Unable to infer base url. This is common when using dynamic servlet
registration or when the API is behind an API Gateway. The base url is
the root of where all the swagger resources are served. For e.g. if
the api is available at http://example.org/api/v2/api-docs then the
base url is http://example.org/api/. Please enter the location
manually:

可能由以下几个原因造成：

1、需要在SpringBoot的启动Application前面加上 @EnableSwagger2注解；
2、可能是由于使用了Spring Security 影响：尝试使用以下Spring Security配置解决：
spring-security需要放开以下拦截：
.pathMatchers( ...,
 "/swagger-resources/**",
 "/swagger-ui.html",
 "/swagger-ui/**",
 "/v2/api-docs",
 "/webjars/**",...）.permitAll()