一、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
展现效果：
