文章目录
Spring Cloud 项目在网关聚合 Swagger 文档
示例代码:Gitee 仓库 中的
项目 | 说明 |
---|---|
swagger-2-sample-knife4j-cloud | swagger 请求走网关 |
各个微服务的改动
改动一:新增依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-micro-spring-boot-starter</artifactId>
<version>${knife4j.version}</version> <!-- 3.0.3 -->
<exclusions>
<exclusion>
<groupId>javax.validation</groupId>
<artifactId>validation-api</artifactId>
</exclusion>
</exclusions>
</dependency>
改动二:新增配置类
@Configuration
@EnableOpenApi
@RequiredArgsConstructor
public class SwaggerConfiguration {
private final OpenApiExtensionResolver openApiExtensionResolver;
@Value("${spring.application.name}")
private String applicationName;
@Bean
@Order(value = 1)
public Docket docDocket() {
return new Docket(DocumentationType.OAS_30)
.pathMapping("/" + applicationName) // ==> /department-service
.enable(true)
.apiInfo(groupApiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class))
.paths(PathSelectors.any())
.build()
.extensions(openApiExtensionResolver.buildExtensions("部门微服务"))
;
}
private ApiInfo groupApiInfo() {
return new ApiInfoBuilder()
.title("Knife4j接口文档")
.description("Knife4j接口文档")
.termsOfServiceUrl("https://doc.xiaominfo.com/")
.version("1.0.0")
.build();
}
}
关键项说明
上述内容,无论是 pom 引包,还是加配置类,绝大部分内容都是复制粘贴,无需改动的。
但是在配置类中,有一个信息必须注意,它必须和你的 spring-cloud 的配置相关:
.pathMapping("/" + applicationName)
.pathMapping() 方法的的值是你的请求通过网关时“必要的前缀”。
换句话说,一个请求经过网关之后,为了确保要能够被网关“转”到你的当前微服务中,网关所收到的请求 URI 中的前缀必须是一个特定的、约定好的内容。
在这里(默认情况下),我们都是以微服务的服务名作为前缀。这个值,就是项目配置文件中的 spring.application.name
配置项的值。
所以,(不出意外的话):
- 如果是 xxx-service 的 Swagger 配置,这里的 .pathMapping() 方法的值应该是 “/xxx-service”;
- 如果是 yyy-service 的 Swagger 配置,这里的 .pathMapping() 方法的值应该是 “/yyy-service”;
- 如果是 zzz-service 的 Swagger 配置,这里的 .pathMapping() 方法的值应该是 “/zzz-service”。
Gateway 的改动
改动一:新增依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j.version}</version> <!-- 3.0.3 -->
</dependency>
改动二:新增配置类和处理类
提示:以下三个类你可以专门放在一个 swagger 包中进行统一管理。
@Component
public class SwaggerHeaderFilter extends AbstractGatewayFilterFactory {
private static final String HEADER_NAME = "X-Forwarded-Prefix";
private static final String URI = "/v3/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);
};
}
}
@Primary
@Configuration
@RequiredArgsConstructor
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()));
// resources为所有路由都加载到文档,如果需要部分显示,在下方使用filter进行过滤即可
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("**", "v3/api-docs"))));
});
return resources;
}
private SwaggerResource swaggerResource(String name, String url) {
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(url);
swaggerResource.setUrl(url);
swaggerResource.setSwaggerVersion("3.0");
return swaggerResource;
}
}
@RestController
public class SwaggerHandler {
@Qualifier
private final SwaggerResourcesProvider swaggerResources;
public SwaggerHandler(SwaggerResourcesProvider swaggerResources) {
this.swaggerResources = swaggerResources;
}
@GetMapping("/swagger-resources")
public Mono<ResponseEntity<List<SwaggerResource>>> swaggerResources() {
return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
}
}
以上三个新增代码都不需要做任何改动。
改动三:改动配置文件
本来,我们的网关项目的配置文件中有个配置项:
spring:
cloud:
gateway:
discovery:
locator:
enabled: true
这个配置项“帮”我们省略掉了大段的、啰嗦的配置简化了配置文件的内容。
但是,出人意料的是:它对我们引入的 Swagger/Knife4j 无效!
所以,如果我们需要网关处引入 Swagger,用以聚合各个微服务的 Swagger,那么,我们需要把这个简写配置项还原成以前大段的、啰嗦的写法…
例如:
spring:
cloud:
gateway:
routes:
- id: 部门微服务
uri: lb://department-service
predicates:
- Path=/department-service/**
filters:
- RewritePath=/department-service/(?<segment>.*), /${segment}
- id: 员工微服务
uri: lb://employee-service
predicates:
- Path=/employee-service/**
filters:
- RewritePath=/employee-service/(?<segment>.*), /${segment}
上面的配置内容,就是以前被一个配置项简化掉的、现在需要再还原回来的内容。它的意思是:
-
当网关收到以
/department-service/
开头的请求,就“转给” department-service,并且将请求 URI 前段的/department-service/
部分截去。 -
当网关收到以
/employee-service/
开头的请求,就“转给” employee-service,并且将请求 URI 前段的/department-service/
部分截去。