Swagger2 自動(dòng)化測(cè)試與文檔

1. 前言

使用 Spring Boot 后，開(kāi)發(fā)人員心里美美的，再也不需要寫一大堆的配置文件了。

每天都能早早地下班，回家可以多打兩把王者榮耀啦。

但是每次開(kāi)發(fā)完后端接口，使用 Postman 測(cè)試比較麻煩。差不多的接口地址，差不多的參數(shù)，每次測(cè)試都要輸入一遍，挺煩心。

另外前端那些家伙，完全不懂后端技術(shù)，天天要文檔。就這么簡(jiǎn)簡(jiǎn)單單幾個(gè)接口，還得給前端寫。

咦，能不能自動(dòng)生成接口文檔，然后自動(dòng)生成測(cè)試界面呢。

百度一搜 "Spring Boot 接口自動(dòng)化測(cè)試"，發(fā)現(xiàn)很多文章推薦使用 Swagger2 。哈哈，站在巨人的肩膀上果然好辦事。

2. Swagger2 功能

Swagger2 可以識(shí)別控制器中的方法，然后自動(dòng)生成可視化的測(cè)試界面。

后端開(kāi)發(fā)人員編寫完 Spring Boot 后端接口后，直接可視化測(cè)試就行了。無(wú)需借助 Postman 等工具，也無(wú)需編寫測(cè)試類和測(cè)試方法，更無(wú)需聯(lián)系前端開(kāi)發(fā)確認(rèn)接口是否正常。

如果給控制器方法添加注解，還能自動(dòng)生成在線 API 文檔，簡(jiǎn)直太省心了。

3. Spring Boot 中使用 Swagger2 流程

還是先思考整體流程，再動(dòng)手落地。

我們繼續(xù)使用上一篇文章中的 spring-boot-restful 項(xiàng)目，為其添加 Swagger2 相關(guān)功能。

3.1 引入 Swagger2 相關(guān)依賴

修改 pom.xml 文件，引入 Swagger2 相關(guān)依賴。

實(shí)例：

	<!-- 添加swagger2相關(guān)功能 -->
   	<dependency>
   		<groupId>io.springfox</groupId>
   		<artifactId>springfox-swagger2</artifactId>
   		<version>2.9.2</version>
   	</dependency>
   	<!-- 添加swagger-ui相關(guān)功能 -->
   	<dependency>
   		<groupId>io.springfox</groupId>
   		<artifactId>springfox-swagger-ui</artifactId>
   		<version>2.9.2</version>
   	</dependency>

3.2 啟用并配置 Swagger2 功能

我們添加一個(gè)配置類，專門用于配置 Swagger2 相關(guān)功能，這樣比較清晰點(diǎn)。通過(guò) @EnableSwagger2 注解開(kāi)啟 Swagger2 功能，通過(guò) @Bean 標(biāo)注的方法將對(duì) Swagger2 功能的設(shè)置放入容器。

實(shí)例：

@Configuration // 告訴Spring容器，這個(gè)類是一個(gè)配置類
@EnableSwagger2 // 啟用Swagger2功能
public class Swagger2Config {
	/**
	 * 配置Swagger2相關(guān)的bean
	 */
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("com"))// com包下所有API都交給Swagger2管理
				.paths(PathSelectors.any()).build();
	}

	/**
	 * 此處主要是API文檔頁(yè)面顯示信息
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("演示項(xiàng)目API") // 標(biāo)題
				.description("學(xué)習(xí)Swagger2的演示項(xiàng)目") // 描述
				.termsOfServiceUrl("http://idcbgp.cn") // 服務(wù)網(wǎng)址，一般寫公司地址
				.version("1.0") // 版本
				.build();
	}
}

3.3 使用 Swagger2 進(jìn)行接口測(cè)試

此時(shí)我們啟動(dòng)項(xiàng)目，然后訪問(wèn) http://127.0.0.1:8080/swagger-ui.html ，即可打開(kāi)自動(dòng)生成的可視化測(cè)試頁(yè)面，如下圖。

嗯，感覺(jué)這個(gè)頁(yè)面簡(jiǎn)單整潔，直接給測(cè)試人員使用都很方便。我們以 update 方法為例演示下如何測(cè)試。先看看該方法的代碼：

實(shí)例：

	/**
	 * 修改商品
	 */
	@PutMapping("/goods/{id}")
	public void update(@PathVariable("id") long id, @RequestBody GoodsDo goods) {
		// 修改指定id的商品信息
		goods.setId(id);
		goodsService.editGoods(goods);
	}

測(cè)試時(shí)先選中對(duì)應(yīng)的方法 update , 然后點(diǎn)擊 Try it out 開(kāi)始測(cè)試。

在參數(shù)區(qū)域輸入 id 和 goods 的值。

點(diǎn)擊 Execute 后，返回 Code 為 200 表示 http 請(qǐng)求成功！

由此可見(jiàn)， Swagger2 將接口以可視化的方式呈現(xiàn)出來(lái)，開(kāi)發(fā)人員不必手輸接口地址、參數(shù)名稱，就可以發(fā)起測(cè)試并查看結(jié)果，確實(shí)非常方便。

后端人員在開(kāi)發(fā)完成后，可以自己使用 Swagger2 測(cè)試下接口可行性。而前端人員也可以打開(kāi) Swagger2 網(wǎng)頁(yè)直接驗(yàn)證接口功能。

3.4 使用 Swagger2 生成在線 API 文檔

使用 Swagger2 生成在線文檔比較簡(jiǎn)單，直接在控制器方法上添加注解即可。如下：

實(shí)例：

@Api(tags = "商品API") // 類文檔顯示內(nèi)容
@RestController
public class GoodsController {
	@Autowired
	private GoodsService goodsService;
	@ApiOperation(value = "根據(jù)id獲取商品信息") // 接口文檔顯示內(nèi)容
	@GetMapping("/goods/{id}")
	public GoodsDo getOne(@PathVariable("id") long id) {
		return goodsService.getGoodsById(id);
	}
	@ApiOperation(value = "獲取商品列表") // 接口文檔顯示內(nèi)容
	@GetMapping("/goods")
	public List<GoodsDo> getList() {
		return goodsService.getGoodsList();
	}
	@ApiOperation(value = "新增商品") // 接口文檔顯示內(nèi)容
	@PostMapping("/goods")
	public void add(@RequestBody GoodsDo goods) {
		goodsService.addGoods(goods);
	}
	@ApiOperation(value = "根據(jù)id修改商品信息") // 接口文檔顯示內(nèi)容
	@PutMapping("/goods/{id}")
	public void update(@PathVariable("id") long id, @RequestBody GoodsDo goods) {
		goods.setId(id);
		goodsService.editGoods(goods);
	}
	@ApiOperation(value = "根據(jù)id刪除商品") // 接口文檔顯示內(nèi)容
	@DeleteMapping("/goods/{id}")
	public void delete(@PathVariable("id") long id) {
		goodsService.removeGoods(id);
	}
}

此時(shí)再次打開(kāi) http://127.0.0.1:8080/swagger-ui.htm ，會(huì)發(fā)現(xiàn)相關(guān)接口都已經(jīng)有文字描述了。

4. 視頻演示

5. 小結(jié)

一般公司在開(kāi)發(fā)時(shí)，可以使用 Swagger2 快速實(shí)現(xiàn)測(cè)試，并生成在線文檔。

由于開(kāi)發(fā)階段經(jīng)常會(huì)修改接口，所以編寫紙質(zhì)文檔實(shí)在是勞民傷財(cái)。如果使用 Swagger2 ，重啟 Spring Boot 后刷新頁(yè)面，就能看到最新 API 文檔。

還有一個(gè)小技巧，我們可以開(kāi)啟熱部署。當(dāng)我們的代碼發(fā)生變化時(shí)， Spring Boot 會(huì)自動(dòng)重啟，這樣就省得每次都要手工重啟 Spring Boot 。

實(shí)例：

	    <!-- 引入該依賴即可開(kāi)啟熱部署 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
		</dependency>

通過(guò)引入依賴，簡(jiǎn)單配置，就能實(shí)現(xiàn)一個(gè)非常棒的功能，這就是 Spring Boot 開(kāi)箱即用的優(yōu)點(diǎn)體現(xiàn)。