Swagger2 自動化測試與文檔

1. 前言

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

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

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

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

咦，能不能自動生成接口文檔，然后自動生成測試界面呢。

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

2. Swagger2 功能

Swagger2 可以識別控制器中的方法，然后自動生成可視化的測試界面。

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

如果給控制器方法添加注解，還能自動生成在線 API 文檔，簡直太省心了。

3. Spring Boot 中使用 Swagger2 流程

還是先思考整體流程，再動手落地。

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

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

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

實例：

	<!-- 添加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 功能

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

實例：

@Configuration // 告訴Spring容器，這個類是一個配置類
@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文檔頁面顯示信息
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("演示項目API") // 標(biāo)題
				.description("學(xué)習(xí)Swagger2的演示項目") // 描述
				.termsOfServiceUrl("http://idcbgp.cn") // 服務(wù)網(wǎng)址，一般寫公司地址
				.version("1.0") // 版本
				.build();
	}
}

3.3 使用 Swagger2 進行接口測試

此時我們啟動項目，然后訪問 http://127.0.0.1:8080/swagger-ui.html ，即可打開自動生成的可視化測試頁面，如下圖。

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

實例：

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

測試時先選中對應(yīng)的方法 update , 然后點擊 Try it out 開始測試。

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

點擊 Execute 后，返回 Code 為 200 表示 http 請求成功！

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

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

3.4 使用 Swagger2 生成在線 API 文檔

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

實例：

@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);
	}
}

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

4. 視頻演示

5. 小結(jié)

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

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

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

實例：

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

通過引入依賴，簡單配置，就能實現(xiàn)一個非常棒的功能，這就是 Spring Boot 開箱即用的優(yōu)點體現(xiàn)。