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-servicepredicates:  - 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/ 部分截去。