Swagger 可以自動生成線上接口文檔，界面可視化的同時保證了便利的測試接口。
1. Swagger2 介紹
Swagger 是一個規範和完整的架構，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目标是使用戶端和檔案系統作為伺服器以同樣的速度來更新。
随着前後端技術的日漸成熟，前後端的互動就隻有接口了，前端請求接口擷取資料，是以接口的格式化也就相當重要，有一個标準格式的接口文檔在開發過程中是相當重要的，swagger就是這麼一個線上的接口文檔，在SpringBoot的內建之中也相當便利。
2. maven 配置Swagger2依賴
建立一個SpringBoot web 項目，然後在pom.xml中添加如下依賴：
io.springfox springfox-swagger-ui 2.2.2 io.springfox springfox-swagger2 2.2.2
3. Swagger2 配置
在Springboot啟動類的同級目錄下面建立一個config的包，然後建立一個配置Swagger2 的配置類。
package com.bowen.config;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** *
springboot-study
springboot-study
*
Swagger 配置類
* @author : zhang.bw * @date : 2020-08-01 16:16 **/@[email protected] class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // 指定建構api文檔的詳細資訊的方法：apiInfo() .apiInfo(apiInfo()) .select() // 指定要生成api接口的包路徑，這裡把controller作為包路徑，生成controller中的所有接口 .apis(RequestHandlerSelectors.basePackage("com.bowen.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() // 設定頁面标題 .title("Spring Boot 內建Swagger接口文檔") // 設定接口描述 .description("Spring Boot 技術棧快速實戰課程") // 設定聯系方式 .contact("微信公衆号【猿碼天地】，" + "https://blog.csdn.net/zbw125") // 設定版本 .version("1.0") // 建構 .build(); }}
配置代碼說明：
- 使用 @Configuration 注解，辨別這是一個配置類，項目啟動的時候會自動調用加載，@EnableSwagger2 注解的作用是自動開啟swagger2。
- apiInfo() 方法裡面的參數可以自己設定，在第一個方法中，我們除了可以根據接口所在的包對應生成接口文檔還可以根據項目中是否有方法使用了 @ApiOperation注解來判斷是否生成api文檔。
4. Controller 測試編寫以及注解說明
上面我們配置好了swagger api生成的配置之後就可以編寫測試的controller，建立一個與config同級的包controller，然後裡面寫一個TestController
package com.bowen.controller;import com.bowen.entiy.JsonResult;import com.bowen.entiy.User;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import org.springframework.web.bind.annotation.*;/** *
springboot-study
springboot-study
*
測試Controller
* @author : zhang.bw * @date : 2020-08-01 16:16 **/@[email protected]("/test")@Api(value = "Swagger2 線上接口文檔")public class TestController { @GetMapping("/get/{id}") @ApiOperation(value = "根據使用者ID擷取使用者資訊") public JsonResult getUserInfo(@PathVariable @ApiParam(value = "使用者ID") Long id) { User user = new User(id, "猿碼天地", "微信公衆号【猿碼天地】"); return new JsonResult(user); } @PostMapping("/insert") @ApiOperation(value = "添加使用者資訊") public JsonResult insertUser(@RequestBody @ApiParam(value = "使用者資訊") User user) { // 業務邏輯省略 return new JsonResult<>(); }}
@RestController 相當于@[email protected] 注解，讓辨別的這個類傳回json格式的資料。
類上面加上@Api的注解，說明這個類要生成api文檔，并給予描述。相當于可以根據這個類作為類别的劃分。在類裡面的方法加上@ApiOperation 注解 用來描述這個方法(接口)是用來做什麼的。
5. 接口測試
完成配置後，啟動項目，浏覽器輸入localhost:8080/swagger-ui.html
swagger-ui頁面
測試一個接口，根據使用者ID擷取使用者資訊：
swagger-ui頁面
傳回結果：
swagger-ui頁面
6. 總結
本文主要講解了swagger2的配置，用法，以及測試，整個流程都講解的非常詳細，相信通過本節課程的學習，對Spring Boot 內建Swagger接口文檔有了全面的認識。
7. 源碼擷取
我是猿人，一個在網際網路打拼的工具人，Java研究猿，感謝各位點贊、收藏和評論，我們下期見！
文章持續更新，可以 私信 001 免費擷取源碼和文檔！