今天我們講一講Swagger這個框架。
一、準備工作
首先說說POM文件里面需要加什么依賴
<!-- Swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
以上為Swagger需要的依賴
接下來需要一個Swagger配置類
Swagger配置類
以下為配置類代碼
@Configuration
@ComponentScan(basePackages = { "com.test.controller" })//配置controller路徑
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.test"))//掃描com路徑下的api文檔
.paths(PathSelectors.any())//路徑判斷,這里是任何路徑
.build();
}
private ApiInfo apiInfo() {
return new ApiInfo("測試接口-JAVA版",//大標題
"測試",//小標題
"1.0",//版本
"001",
"老虎",//作者
"官方網址",//鏈接顯示文字
"www.baidu.com"http://網站鏈接
);
}
}
apiInfo
apiInfo中有一些，作者也沒弄明白的，其實是懶得看了。如果大家知道，請在博客下方留言，謝謝。
到這兒就算是準備工作完成了，接下來介紹一下Swagger的注解。注解，我只會講比較常用的。就是開發過程中用到的，那些太偏門的，就留著有空慢慢研究吧。
二、Swagger注解
先來看個截圖，根據截圖我們講解一下注解
注解
2.1@ApiModel
該注解用于描述Model類
主要使用：
value: 類的說明
reference: 這個本人也沒搞明白做啥的,有明白的請在博客留言啊 ~~~~(>_<)~~~~
2.2@ApiModelProperty
該注解主要用于字段屬性。如果跟用于Controller的注解結合使用，就會有意向不到的效果
主要使用：
value: 字段說明
dataType: 字段類型描述（String、Integer之類的）
required: 是否為空;不用的時候,不寫默認為false
example:字段示例值,用于Swagger文檔頁面展示使用
以上兩個注解主要是用于Model類的。在Swagger頁面上顯示如圖
image.png
image.png
有沒有發現一個問題，第一張圖跟第二張圖少了許多。
沒錯，就是接下來我們要講的用于Controller的注解。
Controller代碼
@RestController
@RequestMapping("test")
@Api(value = "測試", description = "測試Controller", tags = "test")
public class TestController {
@ApiOperation(value="獲取用戶列表", notes="獲取用戶列表", httpMethod = "POST",
response = TestUser.class, produces = "application/json")
@RequestMapping("getUserList")
public List<TestUser> getUserList(@RequestBody @ApiParam TestUser tu) {
List<TestUser> r = new ArrayList<TestUser>();
return r;
}
}
2.3@Api
value:用于描述Controller,與tags相沖
tags:用于歸納Controller,與value相沖
value跟tags這倆,如果有了tags的話,value則無效,否則value有效。
description: Controller的描述
如圖
image.png
2.4@ApiOperation
主要用于修飾Controller類的方法
value: 方法描述
notes: 方法進一步詳細描述
response: 方法返回值必須是 xxx.class
produces: 方法返回類型 基本是application/json
如圖
image.png
雙擊紅框處，紅框的內容會到橢圓形的位置去。點擊左下角的try it out即可發起請求進行測試。
