knife4j 集成Spring Cloud Gateway
更多关于knife4j的详细介绍请参考官方文档
本篇博客主要讲解通过knife4j项目如何集成Spring Cloud Gateway网关,通过网关聚合所有的Swagger微服务文档
源码地址请参考：knife4j-spring-cloud-gateway
整体项目结构如下：
|-knife4j-spring-cloud-gateway
|-----service-doc //文档聚合中心,是所有微服务文档的出口
|-----service-order //订单服务,包含所有与订单业务模块相关的接口
|-----service-server //eureka 注册中心
|-----service-user //用户服务,包含所有的用户接口
eureka注册中心
注册中心几乎没有代码,只是在pom.xml文件中引入了eureka服务的jar包
<dependency>
<groupId>org.springframework.cloudgroupId>
<artifactId>spring-cloud-starter-netflix-eureka-serverartifactId>
dependency>
项目的application.yml配置文件如下：
server:
port: 10000
eureka:
instance:
hostname: localhost
client:
register-with-eureka: false
fetch-registry: false
service-url:
defaultZone: http://${eureka.instance.hostname}:${server.port}/eureka/
spring:
application:
name: knife4j-gateway-server
定义注册中心访问地址，端口号等属性
最后通过注解@EnableEurekaServer来启用注册中心
@EnableEurekaServer
@SpringBootApplication
public class ServiceServerApplication {
}
服务接口(订单order & 用户User)
由于服务接口订单和用户两个模块其实属性是差不多,只是接口不一样,因此就随便挑一个服务的配置来说吧
service-user:用户服务的接口
每个微服务只需要引入和swagger相关的后端jar包即可,不需要引入swagger的前端Ui包,knife4j为我们提供了微服务项的starter,供开发者使用
当然,作为子服务,还需要引入eureka-client的jar包,所以，pom.xml文件相关配置如下：
<dependency>
<groupId>org.springframework.bootgroupId>
<artifactId>spring-boot-starter-webartifactId>
dependency>
<dependency>
<groupId>org.springframework.cloudgroupId>
<artifactId>spring-cloud-starter-netflix-eureka-clientartifactId>
dependency>
<dependency>
<groupId>org.springframework.bootgroupId>
<artifactId>spring-boot-starter-testartifactId>
<scope>testscope>
dependency>
<dependency>
<groupId>com.github.xiaoymingroupId>
<artifactId>knife4j-micro-spring-boot-starterartifactId>
dependency>
项目的jar包引入完成后,接下来是配置swagger的相关配置，SwaggerConfiguration.java配置如下：
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUi
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
@Bean(value = "userApi")
@Order(value = 1)
public Docket groupRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(groupApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xiaominfo.swagger.service.user.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo groupApiInfo(){
return new ApiInfoBuilder()
.title("swagger-bootstrap-ui很棒~~~！！！")
.description("swagger-bootstrap-ui-demo RESTful APIs")
.termsOfServiceUrl("http://www.group.com/")
.contact("[email protected]")
.version("1.0")
.build();
}
}
配置扫描目录包
通过@EnableSwagger2和@EnableSwaggerBootstrapUi来开启swagger和增强特性
配置项目的application.yml文件,如下：
server:
port: 10001
spring:
application:
name: service-user
eureka:
client:
serviceUrl:
defaultZone: http://localhost:10000/eureka/
指定注册中心地址即可
最后,启用eureka客户端
@EnableEurekaClient
@SpringBootApplication
public class ServiceUserApplication {
}
当然,在服务的模块中还有和自己服务相关的业务接口(Controller代码),在这里就不列举了
订单模块(service-order)的代码配置和用户是类似的
文档聚合
有了eureka注册中心,服务模块的接口也已完成,最后一步是把我们所有的微服务都聚合到一个文档,统一输出到前端,供开发者调用了
pom引入相关jar包
service-doc也是一个eureka客户端,首先引入相关的jar包,pom.xml配置文件如下：
<dependency>
<groupId>org.springframework.cloudgroupId>
<artifactId>spring-cloud-starter-netflix-eureka-clientartifactId>
dependency>
<dependency>
<groupId>org.springframework.cloudgroupId>
<artifactId>spring-cloud-starter-gatewayartifactId>
dependency>
<dependency>
<groupId>com.github.xiaoymingroupId>
<artifactId>knife4j-spring-boot-starterartifactId>
dependency>
- spring-cloud-starter-netflix-eureka-client:eureka客户端
- spring-cloud-starter-gateway：gateway网关
- knife4j-spring-boot-starter：knife4j提供的前端ui和后端代码
另外,其实在文档这里,如果没有后端代码编写的话,仅仅引入一个swagger的前端ui模块也是可以的
<dependency>
<groupId>com.github.xiaoymingroupId>
<artifactId>knife4j-spring-uiartifactId>
dependency>
application文件配置
配置我们的网关属性,路由规则等,application.yml配置文件如下：
server:
port: 10003
spring:
application:
name: service-doc
cloud:
gateway:
discovery:
locator:
# enabled: true
lowerCaseServiceId: true
routes:
- id: service-user
uri: lb://service-user
predicates:
- Path=/user/**
# - Header=Cookie,Set-Cookie
filters:
- SwaggerHeaderFilter
- StripPrefix=1
- id: service-order
uri: lb://service-order
predicates:
- Path=/order/**
filters:
- SwaggerHeaderFilter
- StripPrefix=1
eureka:
client:
serviceUrl:
defaultZone: http://localhost:10000/eureka/
logging:
level:
org.springframework:cloud.gateway: debug
文档聚合业务编码
在我们使用Spring Boot等单体架构集成swagger项目时,是通过对包路径进行业务分组,然后在前端进行不同模块的展示,而在微服务架构下,我们的一个服务就类似于原来我们写的一个业务组
springfox-swagger提供的分组接口是swagger-resource,返回的是分组接口名称、地址等信息
在Spring Cloud微服务架构下,我们需要重写该接口,主要是通过网关的注册中心动态发现所有的微服务文档,代码如下：
@Slf4j
@Component
@Primary
@AllArgsConstructor
public class SwaggerResourceConfig implements SwaggerResourcesProvider {
private final RouteLocator routeLocator;
private final GatewayProperties gatewayProperties;
@Override
public List<SwaggerResource> get() {
List<SwaggerResource> resources = new ArrayList<>();
List<String> routes = new ArrayList<>();
routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId())).forEach(route -> {
route.getPredicates().stream()
.filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
.forEach(predicateDefinition -> resources.add(swaggerResource(route.getId(),
predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")
.replace("**", "v2/api-docs"))));
});
return resources;
}
private SwaggerResource swaggerResource(String name, String location) {
log.info("name:{},location:{}",name,location);
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion("2.0");
return swaggerResource;
}
}
接口：
@RestController
public class SwaggerHandler {
@Autowired(required = false)
private SecurityConfiguration securityConfiguration;
@Autowired(required = false)
private UiConfiguration uiConfiguration;
private final SwaggerResourcesProvider swaggerResources;
@Autowired
public SwaggerHandler(SwaggerResourcesProvider swaggerResources) {
this.swaggerResources = swaggerResources;
}
@GetMapping("/swagger-resources/configuration/security")
public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
}
@GetMapping("/swagger-resources/configuration/ui")
public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));
}
@GetMapping("/swagger-resources")
public Mono<ResponseEntity> swaggerResources() {
return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
}
}
启动配置
最后,项目启动类添加相关注解，代码如下：
@EnableDiscoveryClient
@EnableEurekaClient
@SpringBootApplication
public class ServiceDocApplication {
public static void main(String[] args) {
SpringApplication.run(ServiceDocApplication.class, args);
}
}
文档展示
最后分别依次启动项目：
- service-server
- service-user
- service-order
- service-doc
打开文档地址：http://localhost:10003/doc.html
查看文档效果如下：
注意点
在集成Spring Cloud Gateway网关的时候,会出现没有basePath的情况(即定义的例如/user、/order等微服务的前缀),这个情况在使用zuul网关的时候不会出现此问题,因此,在Gateway网关需要添加一个Filter实体Bean,代码如下：
@Component
public class SwaggerHeaderFilter extends AbstractGatewayFilterFactory {
private static final String HEADER_NAME = "X-Forwarded-Prefix";
private static final String URI = "/v2/api-docs";
@Override
public GatewayFilter apply(Object config) {
return (exchange, chain) -> {
ServerHttpRequest request = exchange.getRequest();
String path = request.getURI().getPath();
if (!StringUtils.endsWithIgnoreCase(path,URI )) {
return chain.filter(exchange);
}
String basePath = path.substring(0, path.lastIndexOf(URI));
ServerHttpRequest newRequest = request.mutate().header(HEADER_NAME, basePath).build();
ServerWebExchange newExchange = exchange.mutate().request(newRequest).build();
return chain.filter(newExchange);
};
}
}
然后在配置文件指定这个filter
spring:
application:
name: service-doc
cloud:
gateway:
discovery:
locator:
# enabled: true
lowerCaseServiceId: true
routes:
- id: service-user
uri: lb://service-user
predicates:
- Path=/user/**
# - Header=Cookie,Set-Cookie
filters:
- SwaggerHeaderFilter
- StripPrefix=1
- id: service-order
uri: lb://service-order
predicates:
- Path=/order/**
filters:
- SwaggerHeaderFilter //指定filter
- StripPrefix=1