白話SpringCloud | 第十一章：路由閘道器(Zuul)：利用swagger2聚合API文件
摘要：
前言
通過之前的兩篇文章，可以簡單的搭建一個路由網關了。而我們知道，現在都奉行 前後端分離 開發，前後端開發的溝通成本就增加了，所以一般上我們都是通過 swagger 進行api文件生成的。現在由於使用了統一路由網關了，都希望各微服務的 api文件 統一的聚合在閘道器服務中，也方便前端使...
前言
通過之前的兩篇文章，可以簡單的搭建一個路由網關了。而我們知道，現在都奉行 前後端分離 開發，前後端開發的溝通成本就增加了，所以一般上我們都是通過 swagger 進行api文件生成的。現在由於使用了統一路由網關了，都希望各微服務的 api文件 統一的聚合在閘道器服務中，也方便前端使用者查閱，不需要每個服務單獨檢視。當然了，也是可以做一個文件索引網頁進行各微服務的api文件連結的。今天，我們就來講下使用 swagger 實現 自動化聚合 微服務文件功能。
注：關於 Swagger 的介紹和使用，由於在之前的 SpringBoot 系列文章中有提及，這裡就不在過多闡述了，不理解的可以點選： ofollow,noindex" target="_blank">第十章：Swagger2的整合和使用 進行檢視，瞭解下基本用法。
Zuul聚合示例
為了實現 自動聚合 功能，簡單來說就是通過 Zuul api獲取所有的路由資訊，根據其具體地址進行自動轉配到 Swagger 的 SwaggerResource 下。
另外，為了專案的獨立，本章節建立個 maven 多模組工程專案。整體結構如下：
同時，會啟動一個基於 Eureka 的註冊服務，具體可以檢視原始碼： spring-cloud-eureka-server 。
微服務端
為了演示，建立兩個微服務 spring-cloud-zuul-service-one 和 spring-cloud-zuul-service-two 。
這裡以構建 spring-cloud-zuul-service-one 為例， spring-cloud-zuul-service-two 基本上是一樣的，可以檢視原始碼示例。
0.引入相關依賴
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- 客戶端依賴 --> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId> </dependency> <!--swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.0</version> </dependency>
1.編寫swagger配置類。
/**
* swagger配置類
* @author oKong
*
*/
@EnableSwagger2
@Configuration
public class SwaggerConfig {
//是否開啟swagger，正式環境一般是需要關閉的，可根據springboot的多環境配置進行設定
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 是否開啟
.enable(swaggerEnabled).select()
// 掃描的路徑包
.apis(RequestHandlerSelectors.basePackage("cn.lqdev.learning.springcloud.zuul.service"))
// 指定路徑處理PathSelectors.any()代表所有的路徑
.paths(PathSelectors.any()).build().pathMapping("/");
}
//設定api資訊
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("路由閘道器(Zuul)：利用swagger2聚合API文件-service-one")
.description("oKong | 趔趄的猿")
// 作者資訊
.contact(new Contact("oKong", "https://blog.lqdev.cn/", "[email protected]"))
.version("1.0.0")
.build();
}
}
2.編寫控制層，設定對外api服務資訊,同時建立了 請求 和 響應 的實體類。
DemoController.java
/**
* demo示例
* @author oKong
*
*/
@RestController
@Api(tags="servicie-one服務")
@Slf4j
public class DemoController {
@GetMapping("/hello")
@ApiOperation(value="demo示例")
public DemoResp hello(DemoReq demoReq) {
log.info("DemoReq:{}", demoReq);
return DemoResp.builder()
.code(demoReq.getCode())
.name(demoReq.getName())
.remark(demoReq.getRemark())
.build();
}
}
DemoReq.java
/**
* 請求實體
* @author oKong
*
*/
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel
public class DemoReq {
@ApiModelProperty(name="code",value="編碼",example="oKong")
String code;
@ApiModelProperty(name="name",value="名稱",example="趔趄的猿")
String name;
@ApiModelProperty(name="remark",value="備註",example="blog：blog.lqdev.cn")
String remark;
}
DemoResp.java
/**
* 響應實體
* @author Okong
*
*/
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel
public class DemoResp {
@ApiModelProperty(name="code",value="編碼",example="oKong")
String code;
@ApiModelProperty(name="name",value="名稱",example="趔趄的猿")
String name;
@ApiModelProperty(name="remark",value="備註",example="blog：blog.lqdev.cn")
String remark;
}
3.編寫啟動類。
/**
* api服務1 示例
* @author oKong
*
*/
@SpringBootApplication
@EnableDiscoveryClient
@Slf4j
public class ServiceOneApplication {
public static void main(String[] args) throws Exception {
SpringApplication.run(ServiceOneApplication.class, args);
log.info("spring-cloud-zuul-service-one啟動!");
}
}
4.新增配置資訊。
spring.application.name=api-service-one
server.port=789
# 註冊中心地址 -此為單機模式
eureka.client.service-url.defaultZone=http://127.0.0.1:1000/eureka
# 啟用ip配置 這樣在註冊中心列表中看見的是以ip+埠呈現的
eureka.instance.prefer-ip-address=true
# 例項名稱最後呈現地址：ip:2000
eureka.instance.instance-id=${spring.cloud.client.ip-address}:${server.port}
# swagger開關
swagger.enabled=true
5.啟動應用，訪問：http://127.0.0.1:789/swagger-ui.html 就可以單應用api文件配置成功了
路由閘道器端
建立專案： spring-cloud-zuul-gateway
關於zuul的使用，可以檢視： 第九章：路由閘道器(Zuul)的使用
0.引入相關依賴。
<!-- zuul 依賴 --> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-netflix-zuul</artifactId> </dependency> <!-- 客戶端依賴 --> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId> </dependency> <!--swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.0</version> </dependency>
1.新增相關配置資訊。
spring.application.name=zuul-gateway
server.port=8899
# 註冊中心地址 -此為單機模式
eureka.client.service-url.defaultZone=http://127.0.0.1:1000/eureka
# 啟用ip配置 這樣在註冊中心列表中看見的是以ip+埠呈現的
eureka.instance.prefer-ip-address=true
# 例項名稱最後呈現地址：ip:15678
eureka.instance.instance-id=${spring.cloud.client.ip-address}:${server.port}
# swagger開啟開關
swagger.enabled=true
2.編寫swagger配置類(重點)
@EnableSwagger2
@Configuration
@Primary //多個bean時 此類優先使用
public class SwaggerConfig implements SwaggerResourcesProvider{
//是否開啟swagger，正式環境一般是需要關閉的，可根據springboot的多環境配置進行設定
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;
@Autowired
RouteLocator routeLocator;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 是否開啟
.enable(swaggerEnabled).select()
// 掃描的路徑包
.apis(RequestHandlerSelectors.basePackage("cn.lqdev.learning.springcloud.zuul.swagger2"))
// 指定路徑處理PathSelectors.any()代表所有的路徑
.paths(PathSelectors.any()).build().pathMapping("/");
}
//設定api資訊
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("路由閘道器(Zuul)：利用swagger2聚合API文件")
.description("oKong | 趔趄的猿")
// 作者資訊
.contact(new Contact("oKong", "https://blog.lqdev.cn/", "[email protected]"))
.version("1.0.0")
.termsOfServiceUrl("https://github.com/xie19900123/")
.build();
}
@Override
public List<SwaggerResource> get() {
//利用routeLocator動態引入微服務
List<SwaggerResource> resources = new ArrayList<>();
resources.add(swaggerResource("zuul-gateway","/v2/api-docs","1.0"));
//迴圈 使用Lambda表示式簡化程式碼
routeLocator.getRoutes().forEach(route ->{
//動態獲取
resources.add(swaggerResource(route.getId(),route.getFullPath().replace("**", "v2/api-docs"), "1.0"));
});
//也可以直接 繼承 Consumer介面
//routeLocator.getRoutes().forEach(new Consumer<Route>() {
//
//@Override
//public void accept(Route t) {
//// TODO Auto-generated method stub
//
//}
//});
return resources;
}
private SwaggerResource swaggerResource(String name,String location, String version) {
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion(version);
return swaggerResource;
}
}
這裡繼承 SwaggerResourcesProvider 介面是實現聚合api的關鍵，另外通過 RouteLocator 類獲取 路由 列表是實現 自動聚合 的關鍵。
當然，這裡也是可以手動進行新增的。
3.編寫zuul內部控制層。
/**
* zuul 內部提供對外服務示例
* @author oKong
*
*/
@RestController
@RequestMapping("/demo")
@Api(tags="zuul內部rest api")
public class DemoController {
@GetMapping("/hello")
@ApiOperation(value="demo示例",notes="demo示例")
@ApiImplicitParam(name="name",value="名稱",example="oKong")
public String hello(String name) {
return "hi," + name + ",this is zuul api! ";
}
}
4.編寫啟動類。
/**
* zuul使用swagger2聚合微服務api示例
* @author oKong
*
*/
@SpringBootApplication
@EnableZuulProxy
@EnableDiscoveryClient
@Slf4j
public class ZuulSwaggerApplication {
public static void main(String[] args) throws Exception {
SpringApplication.run(ZuulSwaggerApplication.class, args);
log.info("spring-cloud-zuul-gateway啟動!");
}
}
5.啟動應用，訪問：http://127.0.0.1:8899/swagger-ui.html 可以看見頁面顯示的是閘道器專案的 swagger 文件資訊。
現在看看右上角的 Select a spec 下拉框，可以看見下拉框中包含了註冊中心下的所有微服務了。
此時，我們切換下 api-service-one ,可以看見 api-service-one 的api列表了。
切換到 api-service-two ，也可以看見都要的api列表資訊。
參考資料
總結
本章節主要簡單介紹瞭如何在 Zuul 路由閘道器服務利用 Swagger2 進行微服務api的聚合功能。這樣檢視各微服務的api文件就很方便，集中，不需要在切換不同文件地址了。
最後
目前網際網路上大佬都有分享 SpringCloud 系列教程，內容可能會類似，望多多包涵了。 原創不易，碼字不易 ，還希望大家多多支援。若文中有錯誤之處，還望提出，謝謝。
老生常談
499452441 lqdevOps
個人部落格： http://blog.lqdev.cn