SpringBoot之路(8)–使用Swagger2讓咱滴測試和接口文檔更輕鬆

場景

兄弟們，上一篇咱們演示了SpringBoot開發Restful Web項目是多麼的簡單啊，簡直就是簡單到爆炸。反正老哥我用了SpringBoot之後，是再寫不想寫原始的帶有一堆配置的Spring項目了。

誰還不想簡簡單單把事情辦了，好有更多時間陪女朋友逛街買裙子啊？啥？你沒女朋友，那你還不想有更多時間玩優秀麼兄弟，別這麼死腦筋行不？

說正經的，還是找個女朋友是正道！

好的，有了Restful之後，開發後端API接口確實足夠簡單了，但是如何測試捏。

難道爲了測試，就得把前端工程實現了？那還叫啥前後端分離呢。

難道要單獨使用工具測試，比如Postman，功能導師挺全面，但是Postman完全不知道我們的項目是咋回事啊，URL參數都得自己一個一個填，多麻煩啊。

既然我們的程序都擺在這了，各個接口URL地址、參數都是確定的，就不能自動生成可視化的測試界面麼，讓我們把參數填填發起測試就行。

Swagger2用了就是爽

當然行咧，用Swagger2就是咧。不光自動生成可視化測試，還能自動生成接口文檔。

別人來測試的時候，直接看到文檔描述，都不用來問你了。將程序設計的懶人原則發揮到極致。

此處提一點，程序開發就是要足夠懶，才能讓需求方感到：咋這麼容易、這麼好用捏。

具體實現

好了，扯了一大堆，看看怎麼實現。

1、導入依賴

我們還是使用上一章節中的Web項目進行演示，當然也可以使用任何的SpringBoot 2.x版本的項目進行添加Swagger2操作。

然後導入Swagger2相關的依賴，這樣咱們的項目就能支持Swagger2咧，具體依賴項如下：

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

TIPS：爲啥用2.9.2版本？因爲2.9.2是最新版本，炫酷唄！

2、添加Swagger2配置類

通過配置類配置Swagger2相關功能即可，相關要點咱都放註釋中了。需要注意的是，不要感覺很難理解，這是人家定義好的類庫，我們其實只要拿過來用就行了，Swagger2重點就是會使用就OK。

@Configuration // 告訴Spring容器，這個類是一個配置類，Spring容器得采用這個類的配置
@EnableSwagger2 // 啓用Swagger2功能
public class Swagger2Config {
	/**
	 * 配置Swagger2相關的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")   //標題
                .description("學習Swagger2的演示項目") //描述
                .termsOfServiceUrl("http://www.forwhatsogood.com") //服務網址，此處是我個人網站地址
                .version("1.0") //版本
                .build();
    }
}

3、配置靜態資源訪問

由於Swagger2相關API文檔html/css/js頁面，而SpringBoot 2.x默認會攔截靜態資源，所以需要通過配置類配置下靜態資源。

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		// 允許一下目錄靜態資源訪問
		registry.addResourceHandler("/statics/**").addResourceLocations("classpath:/statics/");
		registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
	}
}

4、啓動項目並進行查看、測試

啓動項目，在之前的訪問地址http://127.0.0.1:1007後面添加/swagger-ui.html，即訪問http://127.0.0.1:1007/swagger-ui.html。

顯示如下，可見我們控制器重的API方法都被列出來了。

點擊其中一個API，然後點擊try it out，則可以注入參數自動執行並顯示結果，如下圖，大家自己試試就OK。

5、通過註解自動生成API文檔

通過在控制器上添加註解，可以在Swagger頁面生成文檔內容，修改控制器代碼如下：

@Api(tags = "博客API") // 類文檔顯示內容
@RestController // 通過該註解，第一將BlogController註冊爲控制器，第二將其中方法返回值轉換爲json
public class BlogController {
   @Autowired // 自動裝配blogService
   private BlogService blogService;

   @ApiOperation(value = "根據id獲取博客信息") // 接口文檔顯示內容
   @GetMapping("/blog/{id}")
   public BlogDo getOne(@PathVariable("id") long id) {
   	return blogService.getBlogById(id);
   }

   @ApiOperation(value = "獲取博客列表") // 接口文檔顯示內容
   @GetMapping("/blog")
   public List<BlogDo> getList() {
   	return blogService.getBlogList();
   }

   @ApiOperation(value = "新增博客") // 接口文檔顯示內容
   @PostMapping("/blog")
   public void add(@RequestBody BlogDo blog) {
   	blogService.addBlog(blog);
   }

   @ApiOperation(value = "根據id修改博客信息") // 接口文檔顯示內容
   @PutMapping("/blog/{id}")
   public void update(@PathVariable("id") long id, @RequestBody BlogDo blog) {
   	// 修改指定id的博客信息
   	blog.setId(id);
   	blogService.updateBlog(blog);
   }

   @ApiOperation(value = "根據id刪除博客") // 接口文檔顯示內容
   @DeleteMapping("/blog/{id}")
   public void delete(@PathVariable("id") long id) {
   	blogService.deleteBlog(id);
   }
}

添加api註解後，Swagger頁面顯示如下，非常清晰簡便的API文檔，且可以直接點擊調試，抓緊試試吧。

總結

Swagger2測試要比寫前端代碼調試，或者寫Java Http代碼調試，或者通過Postman等工具調試都要方便。

因爲不用寫代碼、可視化、參數自動生成，我們只需要在指定參數位置填寫參數即可。

當然也不是萬能的，比如批量測試、併發測試，這個工具是玩不了的。

所以Swagger的使用場景是作爲API文檔，或者開發完畢後的調整參數測試邏輯正確性。