Swagger2 注解
作為一個程序員艺栈，最討厭兩件事：
- 前輩代碼沒有寫文檔捎泻！
- 自己要去維護文檔诬乞！
偶然間從公司前輩那里了解到了swagger工具，可以幫助自動生成接口文檔谁不，就簡單的了解一下坐梯，寫了一個小demo。
1. 簡介
swagger優(yōu)勢：
- 文檔自動生成刹帕。不用擔(dān)心修改接口代碼之后忘記更新文檔的尷尬吵血。
- 支持在線測試。不需要再用postman等偷溺，可以直接進行測試蹋辅，并獲取內(nèi)容。
當(dāng)然還有很多優(yōu)勢挫掏，沒有研究很深入侦另，自己體會吧。
2. 集成Swagger(SpringBoot)
集成Swagger比較簡單尉共，大概分為三步：
- 添加maven依賴褒傅。
- 增加配置文件。
- API接口增加swagger注解爸邢。
只用了springboot的配置，非SpringBoot項目需要配置資源文件映射拿愧，具體可以參考官網(wǎng)杠河！
2.1. 增加maven依賴
<dependencies>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--生成UI界面-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
2.2. 增加配置文件
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket controllerApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.title("文檔說明--API接口文檔")
.description("包括保存、查詢等")
.contact(new Contact("王二牛同學(xué)", "https://github.com/Grrui", "grrui218@gmail.com"))
.version("版本號:1.0")
.build())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swagger2.controller"))
.paths(PathSelectors.ant("/api/**")) // 如果適配所有api浇辜，可以改為PathSelectors.any()
.build();
}
}
2.3. API接口增加swagger注解券敌。
@Api(tags = "接口服務(wù)", value = "/api/v1/swagger/**")
@RestController
@RequestMapping("/api/v1/swagger")
public class ApiController {
@ApiOperation("保存用戶信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "名字", required = true, paramType = "path"),
@ApiImplicitParam(name = "age", dataType = "int", value = "年齡", required = true, paramType = "query")
})
@PostMapping("/{name}")
@ResponseBody
public Boolean save(
@PathVariable("name") String name,
@RequestParam("age") Integer age
) {
userInfo.put(name, new User(name, age));
return true;
}
}
解釋：學(xué)習(xí)的時候看到有大神總結(jié)過一篇很好的詳解，這里直接貼出來了：
@Api：用在請求的類上柳洋，表示對類的說明
tags="說明該類的作用待诅，可以在UI界面上看到的注解"
value="該參數(shù)沒什么意義，在UI界面上也看到熊镣，所以不需要配置"
@ApiOperation：用在請求的方法上卑雁，說明方法的用途、作用
value="說明方法的用途绪囱、作用"
notes="方法的備注說明"
@ApiImplicitParams：用在請求的方法上测蹲，表示一組參數(shù)說明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數(shù)的各個方面
name：參數(shù)名
value：參數(shù)的漢字說明鬼吵、解釋
required：參數(shù)是否必須傳
paramType：參數(shù)放在哪個地方
· header --> 請求參數(shù)的獲瓤奂住：@RequestHeader
· query --> 請求參數(shù)的獲取：@RequestParam
· path（用于restful接口）--> 請求參數(shù)的獲瘸菀巍：@PathVariable
· body（不常用）
· form（不常用）
dataType：參數(shù)類型琉挖，默認String启泣，其它值dataType="Integer"
defaultValue：參數(shù)的默認值
@ApiResponses：用在請求的方法上，表示一組響應(yīng)
@ApiResponse：用在@ApiResponses中示辈，一般用于表達一個錯誤的響應(yīng)信息
code：數(shù)字寥茫，例如400
message：信息，例如"請求參數(shù)沒填好"
response：拋出異常的類
@ApiModel：用于響應(yīng)類上顽耳，表示一個返回響應(yīng)數(shù)據(jù)的信息
（這種一般用在post創(chuàng)建的時候坠敷，使用@RequestBody這樣的場景，
請求參數(shù)無法使用@ApiImplicitParam注解進行描述的時候）
@ApiModelProperty：用在屬性上射富，描述響應(yīng)類的屬性
3.UI展示
啟動項目膝迎，訪問http://localhost:8080/swagger-ui.html(根據(jù)實際情況修改域名+端口)就可以展示并測試接口功能。
swagger.png
參考：https://blog.csdn.net/xiaojin21cen/article/details/78654652
代碼地址：https://github.com/Grrui/swagger2
