微信公众号:[执着猿哥]
记录和分享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,可自动实现文档网关聚合。