有了Swagger2，再也不用為寫Api文檔頭疼了
1、為什麼要寫Api文檔
現在，前後端分離的開發模式已經非常流行，後端開發工程師只負責完成後端接口，前端頁面的開發和渲染完全由前端工程師完成。
問題來了，前端工程師怎麼知道後端接口的具體定義呢？答案是由後端工程師撰寫。
2、寫Api文檔很頭疼嗎
答案是一定的，這對後端工程師來說，是額外的工作，編碼已經很耗費精力了，這時前端工程師來催文檔，不頭疼才怪：），當然這也不是前端工程師的問題，都是為項目的進度着急。
3、Swagger2
現在好了，一個自動撰寫Api文檔的神器出現了，他就是 Swagger2，Swagger2通過美觀的WEB界面展示了所有接口的定義，非常方便，還能直接在界面上進行測試調用，有助於調試。
後端工程師，定義好接口，加幾個註解，便能自動生成在線接口定義，前端工程師可以實時的看到。
下面就來講講如何把 Swagger2 整合到項目中來。
4、接口介紹
這裡以一個簡單的接口作為例子，接口的功能是輸入用戶ID，獲取用戶數據。
5、引入依賴
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
6、增加Swagger2配置類
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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class Swagger2 { // swagger2配置 @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // 指定api類型為swagger2 .apiInfo(apiInfo()) // 用於定義api文檔匯總信息 .select() .apis(RequestHandlerSelectors .basePackage("cn.zhuifengren.controller")) // 指定掃描的controller包 .paths(PathSelectors.any()) // 所有controller .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("hello工程接口api") // 文檔頁標題 .contact(new Contact("hello", "", "")) // 聯繫人信息 .description("專為hello工程提供的api文檔") // 詳細信息 .version("1.0.0") // 文檔版本號 .termsOfServiceUrl("") // 網站地址 .build(); } }
7、在Controller類中增加Swagger2註解
import cn.zhuifengren.model.Result; import cn.zhuifengren.model.User; import cn.zhuifengren.service.UserService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/user") @Api(value = "UserController", tags = "用戶接口") public class UserController { @Autowired private UserService userService; @GetMapping("/info/{id}") @ApiOperation(value = "獲取用戶信息") public Result<User> getUserInfo(@ApiParam(value = "用戶ID") @PathVariable("id") String id) { User userInfo = userService.getUserInfo(id); Result<User> result = new Result<>(); result.setCode(200); result.setMessage("success"); result.setData(userInfo); return result; } }
其中 @Api註解 放在類上，用於對類的描述，@ApiOperation註解 放在方法上，用於對接口方法的描述。
8、模型類中增加Swagger2註解
import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel(value = "用戶實體", description = "用戶實體") public class User { @ApiModelProperty(value = "用戶id", name = "id", example = "1") private String id; @ApiModelProperty(value = "用戶姓名", name = "name", example = "小李") private String name; @ApiModelProperty(value = "用戶年齡", name = "age", example = "36") private Integer age;
其中 @ApiModel註解 放在類上，用於對模型類的描述，@ApiModelProperty註解 放在屬性上，用於對模型屬性的描述。
9、啟動項目查看效果
啟動項目後，進入地址：//localhost:8080/swagger-ui.html，即可看到Swagger2 WEB頁面，點擊【Try it out】按鈕，還可以對接口進行測試，是不是很方便呢，趕快去用一下吧
