Spring Cloud Gateway系列【13】整合knife4j实现网关聚合接口文档

╰+哭是因爲堅強的太久メ 2023-10-09 13:44 73阅读 0赞

#### 文章目录 ####

*   *  前言
     *  方式1 Spring Cloud Gateway
     *   *  1. 后台服务配置 knife4j
         *  2. 网关聚合
     *  方式2 Knife4jAggregation微服务聚合中间件

### 前言 ###

在微服务架构下，每个后台应用都接入swagger 在线文档，在服务特别多的情况下，就需要做聚合文档处理，也就是将所有服务的文档聚合在一起。

`Spring Cloud Gateway`作为微服务的API网关，可以整合swagger 实现聚合接口文档。

### 方式1 Spring Cloud Gateway ###

方式1 使用`Spring Cloud Gateway`直接聚合，使用[knife4j][] 作为在线接口文档。

#### 1. 后台服务配置 knife4j ####

首先在后台应用中添加knife4j 依赖。

<dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                <version>2.0.9</version>
            </dependency>

添加配置类：

@Configuration
    @EnableSwagger2WebMvc
    @EnableKnife4j
    public class SwaggerConfiguration {
        
    
        @Bean(value = "userApi")
        @Order(value = 1)
        public Docket groupRestApi() {
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(groupApiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("org.pearl.app"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo groupApiInfo() {
        
            return new ApiInfoBuilder()
                    .title("swagger-bootstrap-ui很棒~~~！！！")
                    .description("<div style='font-size:14px;color:red;'>swagger-bootstrap-ui-demo RESTful APIs</div>")
                    .termsOfServiceUrl("http://www.group.com/")
                    .contact("group@qq.com")
                    .version("1.0")
                    .build();
        }
    
    }

添加一个测试接口

@RestController
    @RequestMapping("/app1")
    @Api(tags = "测试")
    public class App1Controller {
        
    
    
        @GetMapping("/test")
        @ApiOperation(value = "测试接口")
        @ApiOperationSupport(author = "xiaoymin@foxmail.com")
        public Object test() {
        
            return "app1";
        }
    }

访问`/doc.html`并测试：  
![在这里插入图片描述][watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16]

#### 2. 网关聚合 ####

**思路**： 在文档首页，是有一个分组功能的，如果我们按照服务名来分组，显示在这里，就能实现聚合了。  
![在这里插入图片描述][watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 1]  
可以打开F12，看到，是通过`/swagger-resources` 路径来访问展示资源的，那么我们可以重写这个接口。  
![在这里插入图片描述][watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 2]

首先在`gateway` 项目也引入knife4j 的依赖：

自定义实现`SwaggerResourcesProvider`，在网关中查询路由信息，生成对应的资源信息。

@Component
    @RequiredArgsConstructor
    public class MySwaggerResourceProvider implements SwaggerResourcesProvider {
        
    
        /**
         * swagger2默认的url后缀
         */
        private static final String SWAGGER2_URL = "/v2/api-docs";
    
        /**
         * 路由定位器
         */
        private final RouteLocator routeLocator;
    
        /**
         * 网关应用名称
         */
        @Value("${spring.application.name}")
        private String gatewayName;
    
        /**
         * 获取 Swagger 资源
         */
        @Override
        public List<SwaggerResource> get() {
        
            List<SwaggerResource> resources = new ArrayList<>();
            List<String> routeHosts = new ArrayList<>();
            // 1. 获取路由Uri 中的Host=> 服务注册则为服务名=》app-service001
            routeLocator.getRoutes()
                    .filter(route -> route.getUri().getHost() != null)
                    .filter(route -> !gatewayName.equals(route.getUri().getHost()))
                    .subscribe(route -> routeHosts.add(route.getUri().getHost()));
            // 2. 创建自定义资源
            for (String routeHost : routeHosts) {
        
                String serviceUrl = "/" + routeHost + SWAGGER2_URL; // 后台访问添加服务名前缀
                SwaggerResource swaggerResource = new SwaggerResource(); // 创建Swagger 资源
                swaggerResource.setUrl(serviceUrl); // 设置访问地址
                swaggerResource.setName(routeHost); // 设置名称
                swaggerResource.setSwaggerVersion("3.0.0");
                resources.add(swaggerResource);
            }
            return resources;
        }
    }

添加一个`/swagger-resources` 访问接口，覆盖默认。

@RestController
    @RequestMapping("/swagger-resources")
    @RequiredArgsConstructor
    public class SwaggerResourceController {
        
    
    
        private final  MySwaggerResourceProvider swaggerResourceProvider;
    
        @RequestMapping
        public ResponseEntity<List<SwaggerResource>> swaggerResources() {
        
            return new ResponseEntity<>(swaggerResourceProvider.get(), HttpStatus.OK);
        }
    }

启动项目，访问网关+`/doc.html`，可以看到后台服务名，显示在了分组列表中，然后点击分组，就能显示对应后台的接口文档了，测试正常访问，集成成功。  
![在这里插入图片描述][watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 3]

### 方式2 Knife4jAggregation微服务聚合中间件 ###

[官方文档][Link 1]

自2.0.8版本开始，Knife4j提供的轻量级聚合中间件，也就是不推荐使用`Spring Cloud Gateway` 聚合了，可以采用`aggregation` ，统一集成。  
![在这里插入图片描述][watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 4]

具体集成步骤，官网已经写得很详细了，所以这里就不赘述了，其步骤大概为：

*  安装Knife4jAggregationDesktop
 *  后台添加 `knife4j-aggregation-spring-boot-starter`依赖，配置

[knife4j]: https://doc.xiaominfo.com/knife4j/documentation/description.html
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/d391775c096c4b468ab00d6eb74e3e4d.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg==,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 1]: https://img-blog.csdnimg.cn/1bb751d0ee594b5d928fc79d81b3063b.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg==,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 2]: https://img-blog.csdnimg.cn/c7bc7bc0a5724645967bbeca2ddce3b8.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg==,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 3]: https://img-blog.csdnimg.cn/a324fe754ab3436db120cdd55d2c417f.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg==,size_20,color_FFFFFF,t_70,g_se,x_16
[Link 1]: https://doc.xiaominfo.com/knife4j/documentation/knife4jAggregation.html
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 4]: https://img-blog.csdnimg.cn/ea1202197043408e92b15bccfd25545c.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg==,size_20,color_FFFFFF,t_70,g_se,x_16