白話SpringCloud | 第十一章：路由網關(Zuul)：利用swagger2聚合API文檔

時間  2019-11-06
標籤 白話 springcloud 第十 一章 路由 網關 zuul 利用 swagger2 swagger 聚合 api 文檔 欄目 系統網絡 简体版
原文   原文鏈接

前言

經過以前的兩篇文章，能夠簡單的搭建一個路由網關了。而咱們知道，如今都奉行先後端分離開發，先後端開發的溝通成本就增長了，因此通常上咱們都是經過swagger進行api文檔生成的。如今因爲使用了統一路由網關了，都但願各微服務的api文檔統一的聚合在網關服務中，也方便前端用戶查閱，不須要每一個服務單獨查看。固然了，也是能夠作一個文檔索引網頁進行各微服務的api文檔連接的。今天，咱們就來說下使用swagger實現自動化聚合微服務文檔功能。html

注：關於Swagger的介紹和使用，因爲在以前的SpringBoot系列文章中有說起，這裏就不在過多闡述了，不理解的能夠點擊：第十章：Swagger2的集成和使用進行查看，瞭解下基本用法。前端

Zuul聚合示例

爲了實現自動聚合功能，簡單來講就是經過Zuulapi獲取全部的路由信息，根據其具體地址進行自動轉配到Swagger的SwaggerResource下。java

另外，爲了項目的獨立，本章節建立個maven多模塊工程項目。總體結構以下：git

項目結構

同時，會啓動一個基於Eureka的註冊服務，具體能夠查看源碼：spring-cloud-eureka-server。github

微服務端

爲了演示，建立兩個微服務spring-cloud-zuul-service-one和spring-cloud-zuul-service-two。web

這裏以構建spring-cloud-zuul-service-one爲例，spring-cloud-zuul-service-two基本上是同樣的，能夠查看源碼示例。spring

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配置類。api

/**
 * 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/", "499452441@qq.com"))
				.version("1.0.0")
				.build();
	}
}

2.編寫控制層，設置對外api服務信息,同時建立了請求和響應的實體類。springboot

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文檔配置成功了

service-one-swagger

路由網關端

建立項目：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/", "499452441@qq.com"))
				.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文檔信息。

zuul-gate-swagger-ui

如今看看右上角的Select a spec下拉框，能夠看見下拉框中包含了註冊中心下的全部微服務了。

Select a spec

此時，咱們切換下api-service-one,能夠看見api-service-one的api列表了。

api-service-one

切換到api-service-two，也能夠看見都要的api列表信息。

api-service-two

參考資料

  1. https://piotrminkowski.wordpress.com/2017/04/14/microservices-api-documentation-with-swagger2/

總結

本章節主要簡單介紹瞭如何在Zuul路由網關服務利用Swagger2進行微服務api的聚合功能。這樣查看各微服務的api文檔就很方便，集中，不須要在切換不一樣文檔地址了。

最後

目前互聯網上大佬都有分享SpringCloud系列教程，內容可能會相似，望多多包涵了。原創不易，碼字不易，還但願你們多多支持。若文中有錯誤之處，還望提出，謝謝。

老生常談

  • 我的QQ：499452441
  • 微信公衆號：lqdevOps

公衆號

我的博客：http://blog.lqdev.cn

源碼示例：https://github.com/xie19900123/spring-cloud-learning

如下教程可能你會感興趣：

原文地址：https://blog.lqdev.cn/2018/10/19/SpringCloud/chapter-eleven/

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程