微信公众号：[执着猿哥]
记录和分享java、springcloud等企业级编码技术知识。有问题或建议和源码，请关注公众号。

​ RuoYi 微服务采用Swagger2，替换成Knife4j。Knife4j是swagger的增强方案，可以比swagger更友好的，提供word、markdown等模版下载，更符合国人习惯。当前改造基于Spring Cloud Gateway 网关 + nacos + knife4j 对所有微服务项目的接口文档进行自动聚合，从而实现接口文档管理功能。

Spring Cloud Gateway 整合 Knife4j：

​ 随着系统不断发展，系统中微服务的数量肯定会越来越多，我们不可能每添加一个服务，就在网关配置一个新的路由规则，维护成本太大；微服务中，我们在请求路径中会携带一个路由标识方便进行转发，而这个路由标识一般都是服务在注册中心中的服务名，可开启 spring cloud gateway 的自动路由功能，网关自动根据注册中心的服务名为每个服务创建一个router，将以服务名开头的请求路径转发到对应的服务，完成服务自动聚合。

​ 1、 修改ruoyi-gateway 网关在nacos中的配置ruoyi-gateway-dev.yml ：开启自动聚合以及删除手动router路由，配置完整如下：

```xml
spring:
  redis:
    host: 123.207.216.21
    port: 16979
    password: Rootqwerty123
  cloud:
    gateway:
      discovery:
        locator:
          lowerCaseServiceId: true          
          enabled: true
logging:
  config: file:config/logback.xml            
# 安全配置
security:
  # 验证码
  captcha:
    enabled: true
    type: math
  # 防止XSS攻击
  xss:
    enabled: true
    excludeUrls:
      - /system/notice
  # 不校验白名单
  ignore:
    whites:
      - /auth/logout
      - /auth/login
      - /auth/register
      - /*/v2/api-docs
      - /csrf
      - /csrf1

​ 如上配置删除spring-cloud-gateway下所有routes服务手动配置。其中

• spring.cloud.gateway.discovery.locator.enabled = true:
  默认为false，设置为true表明spring cloud gateway开启服务发现和路由的功能，网关自动根据注册中心的 服务名为每个服务创建一个router，将以服务名开头的请求路径转发到对应的服务
• spring.cloud.gateway.discovery.locator.lower-case-service-id = true
  lowerCaseServiceId：启动 locator.enabled=true 自动路由时，路由的路径默认会使用大写ID，若想要使用小写ID，可将lowerCaseServiceId设置为true

2、ruoyi-gateway 网关工程pom.xml 加入knife4j ui 依赖，在Spring Cloud的微服务架构下，每个微服务并不需要引入前端的ui资源，只需要在网关服务下，把前端的knife4jui资源引入，如下：

	<!-- Swagger 保留-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>${swagger.fox.version}</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>${swagger.fox.version}</version>
		</dependency>
	<!--  knife4j  ui-->
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>knife4j-spring-ui</artifactId>
			<version>3.0.3</version>
		</dependency>

3、ruoyi-gateway 工程修改SwaggerProvider类中的get() 方法,获取服务名称，能够自动获取服务

@Component
public class SwaggerProvider implements SwaggerResourcesProvider, WebFluxConfigurer
{
    /**
     * Swagger2默认的url后缀
     */
    public static final String SWAGGER2URL = "/v2/api-docs";
    /**
     * 网关路由
     */
    @Autowired
    private RouteLocator routeLocator;

    @Autowired
    private GatewayProperties gatewayProperties;
    /**
     * 网关应用名称
     */
    @Value("${spring.application.name}")
    private String applicationName;
    /**
     * 聚合其他服务接口,,这个地方修改。。。。。
     * 
     * @return
     */
    @Override
    public List<SwaggerResource> get()
    {
    	 //接口资源列表
        List<SwaggerResource> resources = new ArrayList<>();
        //服务名称列表
        List<String> routeHosts = new ArrayList<>();
        // 获取所有可用的应用名称
        routeLocator.getRoutes().filter(route -> route.getUri().getHost() != null)
                .filter(route -> !applicationName.equals(route.getUri().getHost()))
                .subscribe(route -> routeHosts.add(route.getUri().getHost()));
        //去重，多负载服务只添加一次
        Set<String> existsServer = new HashSet<>();
        routeHosts.forEach(host -> {
            // 拼接url
            String url = "/" + host + SWAGGER2URL;
            //不存在则添加
            if (!existsServer.contains(url)) {
                existsServer.add(url);
                SwaggerResource swaggerResource = new SwaggerResource();
                swaggerResource.setUrl(url);
                swaggerResource.setName(host);
                resources.add(swaggerResource);
            }
        });
        return resources;
    }
    private SwaggerResource swaggerResource(String name, String location){
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion("2.0");
        return swaggerResource;
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry){
        /** swagger-ui 地址 */
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
    }
}

4、在ruoyi-common-swagger工程中引入knife4j提供的微服务starter

     <!-- Swagger 保留-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.fox.version}</version>
        </dependency>
     <!-- 引入 knife4j 依赖-->
        <dependency>
		    <groupId>com.github.xiaoymin</groupId>
		    <artifactId>knife4j-spring-boot-starter</artifactId>
		    <version>3.0.3</version>
		</dependency>

5、在ruoyi-auth 工程中 pom.xml 引入ruoyi-common-swagger

        <!-- RuoYi Common Swagger -->
        <dependency>
            <groupId>com.ruoyi</groupId>
            <artifactId>ruoyi-common-swagger</artifactId>
        </dependency>

ruoyi-system 工程pom.xml 本身就引入ruoyi-common-swagger依赖，不需要改动

Gateway 整合Knife4j实现自动聚合验证

1 启动ruoyi-gateway 网关工程，此时服务都未启动，所以启动页面都是空白。访问地址： http://127.0.0.1:8080/doc.html#/home，效果如下

2 启动ruoyi-auth 授权工程，可在左侧看到聚合的ruoyi-auth接口文档，效果如下

3 启动ruoyi-system 系统工程，可在左侧看到聚合的ruoyi-system接口文档，效果如下

完成Gateway网关自动聚合各个服务knife4j接口文档，其余各个服务工程只要依赖ruoyi-common-swagger，可自动实现文档网关聚合。