一、Swagger2介紹
Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。
Swagger 的目標是對 REST API 定義一個標准且和語言無關的接口，可以讓人和計算機擁有無須訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。當通過 Swagger 進行正確定義，用戶可以理解遠程服務並使用最少實現邏輯與遠程服務進行交互。與為底層編程所實現的接口類似，Swagger 消除了調用服務時可能會有的猜測。
Swagger的優勢：
1、支持API自動生成同步文檔，使用Swagger之后可以直接通過代碼以及簡單的配置來自動生成文檔。
2、提供web頁面的在線測試API,可以不需要postman等工具進行接口測試，在線測試參數與格式都確定了，直接在web界面進行參數設置就可以測試接口啦。
二、SpringBoot集成Swagger2
1、添加Swagger2依賴
1）UI原生版本
<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>
2）UI增強版本
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<!--在引用時請在maven中央倉庫搜索最新版本號-->
<version>2.0.3</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
2、創建Swagger2配置文件
@Configuration
@EnableSwagger2
@EnableKnife4j//UI增強注解
public class Swagger2Config {
@Bean
public Docket buildDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.dragonsoft.dataManage.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInfo(){
return new ApiInfoBuilder()
//頁面標題，導入postman時必須有該項配置
.title("模擬創建仿真數據")
//版本號，導入postman時必須有該項配置
.version("1.0")
.description("視頻大數據平台基線V1.1-區域分析-業務數據構造")
//創建人
.contact(new Contact("jiangmy","http://localhost:9999/swagger-ui.html","jiangmy@dragoninfo.com.cn"))
.build();
}
}
3、修改Controller，添加API注解
@RestController
@RequestMapping(value = "/ryxx")
@Api(description = "人員基礎信息")
public class PeopleApiController {
@ResponseBody
@GetMapping(value = "/ryjcxx", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@ApiOperation(value = "人員基礎信息",notes = "人員基礎信息生成")
public Map<String,Object> ryjcxx() {
Map<String,Object> returnResult = null;
try {
returnResult = CzrkComponet.ryJcxx();
} catch (Exception e) {
e.printStackTrace();
}
return returnResult;
}
1、注解說明
@Api注解可以用來標記當前Controller的功能。
（1）tags="說明該類的作用，可以在UI界面上看到的注解" （非空時將覆蓋value的值）
（2）value="說明類的作用"
（3）description="說明類的作用，對類的作用進行描述"
@Api(tags = {"教師管理", "教學管理"}，description = "軌跡數據構造-人")
@ApiOperation注解用來標記一個方法的作用。
（1）value="說明該方法的作用和用途"
（2）notes="對該方法的備注信息說明"
@ApiOperation(value = "人臉軌跡和識別結果進出一組數據生成",notes = "根據指定區域、時間、人員，生成進出一組的人臉軌跡（collect_face_info）2條和識別結果數據（engs_comp_clg_result）2條")
@ApiImplicitParam注解用來描述一個參數，可以配置參數的中文含義，也可以給參數設置默認值，這樣在接口測試的時候可以避免手動輸入。
如果有多個參數，則需要使用多個@ApiImplicitParam注解來描述，多個@ApiImplicitParam注解需要放在一個@ApiImplicitParams注解中。
需要注意的是，@ApiImplicitParam注解中雖然可以指定參數是必填的，但是卻不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架內必填，拋棄了Swagger2，這個限制就沒用了，所以假如開發者需要指定一個參數必填，@RequestParam(required = true)注解還是不能省略。
（1）name參數名
（2）value對參數的說明
（3）required參數是否必傳（值為true或者false）
（4）dataType參數類型，默認是String，其他例如：Integer
（5）paramType 參數放在什么地方
· header --> 請求參數的獲取：@RequestHeader ·
query --> 請求參數的獲取：@RequestParam ·
path（用於restful接口）--> 請求參數的獲取：@PathVariable ·
body（不常用） ·
form（不常用）
@ApiImplicitParams({
@ApiImplicitParam(name = "areaName", value = "有效區域名稱（t_area.name），1）區域有效且啟用即t_area.is_delete = '0' and on_off = '0';2）區域內有已授權的人像抓拍用途的進出標識攝像頭即baz_ape_purpose.purpose='2' and is_authorized='t' and aisle_mark in ('1','-1');3) 攝像機設備有效即baz_ape.deleted = '0' and state_ = '1'",defaultValue = "jmy區域", paramType = "query", dataType = "string", required = true),
@ApiImplicitParam(name = "pid", value = "有效人員id(baz_person.pid)，即baz_person表中deleted = 'f'",defaultValue = "8ad0eeec8e3f50e9518ba0a9592bb8c2", paramType = "query", dataType = "string", required = true),
@ApiImplicitParam(name = "collectTime", value = "采集時間起始值，若多條記錄則會自動加1天，格式：2020-02-01 08:00:00,注意：該時間加上record的天數，不可超出系統當前時間，以免造成時間不合理",defaultValue = "2020-02-01 08:00:00", paramType = "query", dataType = "string", required = true),
@ApiImplicitParam(name = "record", value = "進入區域次數，單次進出算1次", defaultValue = "1", paramType = "query", dataType = "int", required = true),
@ApiImplicitParam(name = "hour", value = "單次進出停留時長，注意：進出時長需不超過23:59:59-采集時間點之間的時長取整（例：采集時間點08:00:00，則進出時長不超過23:59:59-08:00:00即15小時）", defaultValue = "12", paramType = "query", dataType = "int", required = true),
@ApiImplicitParam(name = "faceImgUrl", value = "抓拍圖片URL,未填寫時默認取pid的主圖URL即baz_person_img_source.img_url且is_master = 't'且deleted = 'f'，填寫時則按填寫設置", defaultValue = "", paramType = "query", dataType = "string", required = false),
@ApiImplicitParam(name = "sceneImgUrl", value = "全景圖片URL,未填寫時默認取pid的主圖URL即baz_person_img_source.img_url且is_master = 't'且deleted = 'f'，填寫時則按填寫設置", defaultValue = "", paramType = "query", dataType = "string", required = false)
})
@ApiResponses：用在請求的方法上，表示一組響應
@ApiResponse用在@ApiResponses中，常用於表示一組錯誤的信息的響應
（1）code錯誤代碼
（2）massege錯誤信息提示
（3）response 拋出異常的類
示例：
@ApiResponses({
@ApiResponse(code=400,message="請求參數沒填好"),
@ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對")
})
@ApiParam用在請求方法中，描述參數的信息
name參數名稱，參數名稱可以覆蓋方法參數名稱，路徑參數必須與方法參數一致
value參數的簡要說明。
defaultValue參數默認值
required 屬性是否必填，默認為false [路徑參數必須填]
@ApiParam(name = "areaName", required = true) String areaName,
@ApiModelProperty作為字段的描述
實體類使用
@Entity
@Data
@ApiModel(value = "常口")
@Table(name = "T_GA_ZA_RKXXGLXT_CZRK", schema = "CSBSYS", catalog = "")
public class T_GTGaZaRkxxglxtCzrk {
@ApiModelProperty(value = "人員id",required = true)
private String rid;
@ApiIgnore() 用在類或者方法上，表明在swagger2中忽略這個類或者方法或者參數。
不想接口在頁面上顯示可以使用@ApiIgnore()注解
2、Swagger界面排序
參考鏈接：https://blog.csdn.net/suifeng629/article/details/106214262
1、模塊的排序，使用tag名稱排序，在名稱前加上前綴0X-，即在名稱就加上"01-"、"02-"。但為了頁面展示效果，在排序后把前綴進行處理;
@RequestMapping(value = "/people")
@Api(tags = "01-對象-人")
2、接口排序在路徑名前加前綴0X-，即在名稱就加上"01-"、"02-"。
@GetMapping(value = "/01jcxx", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
3、swagger文檔轉成word 文檔
參考鏈接：https://www.cnblogs.com/jmcui/p/8298823.html
4、swagger訪問URL
1、原生版本
http://${host}😒{port}/swagger-ui.html
2、UI增強版本
http://${host}😒{port}/doc.html
展現效果：
