Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。是一套流行的API框架，可以帮助开发人员快速构建API文档，还可以方便测试项目各项功能。
在Guns框架的学习过程中，集成了Swagger，在此了解学习一下。当下的开发现状是前后端分离，开发人员交流凭借一份接口文档即可，但是关于接口文档的构建和测试，是需要较长时间的，因此为了简化开发流程，提高开发效率，基于RESTful的API在线生成框架也就出现了，这里需要提及一下阿里的Rap框架，轻量级API框架，有兴趣的可以去了解下：http://rapapi.org/org/index.do。这里所说的Swagger框架是功能较多的API框架。
废话不多说，开始正题：三步走策略
- SpringBoot整合Swagger2
1.1 首先，在SpringBoot项目中添加Swagger的相关依赖。
这里说一下，关于版本问题，有篇博客说到Swagger2.2.2和SpringBoot1.5.6是绝配。版本问题还是需要注意下。
<swagger.version>2.2.2</swagger.version>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>1.2 创建配置类：SwaggerConfig.java
@Configuration
@EnableSwagger2
public class SwaggerConfig{
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//采用包含注解的方式来确定要显示的接口
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//采用包扫描的方式来确定要显示的接口
//.apis(RequestHandlerSelectors.basePackage("com.xx.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger标题")
.description("Swagger描述")
.termsOfServiceUrl("www.baidu.com")
.contact("actor")
.version("1.0")
.build();
}
}配置类代码分析：
@Configuration：表明该类为配置类，并创建Bean由Spring容器进行管理。
@EnableSwagger2：开启Swagger2。
createRestApi()：创建API应用，apiInfo() 增加API相关信息。通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，这里采用的是注解方式来进行接口暴露，也就是被声明注解的方法才可以被暴露。采用包扫描的方式就是讲设定包路径下的所有controller全部暴露出来。
apiInfo()：配置些展示页面的相关信息。描述、标题、版本、作者等信息。
1.3 配置静态资源映射：由于Swagger是存在UI界面的，集成进SpringBoot后，需要对用于展示的静态资源进行映射，因为这些资源是不通过请求而展示的。在我们的启动类Application.java中添加对Swagger的静态资源支持。
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}资源层次结构为：
2.Swagger注解相关配置
@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
paramType：参数放在哪个地方
header 请求参数的获取：@RequestHeader
query 请求参数的获取：@RequestParam
path （用于restful接口）请求参数的获取：@PathVariable
body （@RequestBody）
form （表单提交）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的含义
defaultValue：参数的默认值
@ApiResponses：用于表示一组响应。
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：描述一个Model的信息
@ApiModelProperty：描述一个model的属性
3.测试Swagger：这里模拟一个请求进行测试上述Swagger常用注解参数。
//测试swagger
@RequestMapping(value = "/test/sw/{num}", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "测试Swagger", notes = "测试SwaggerNotes", tags = {""}, response = String.class)
@ApiImplicitParams({
@ApiImplicitParam(value = "测试字符串", name = "str", required = true, dataType = "String", paramType = "query"),
@ApiImplicitParam(value = "测试数字", name = "num", required = true, dataType = "int", paramType = "path"),
})
public String swaggerTest(@RequestParam String str,@PathVariable Integer num){
return str + num.toString();
}模拟请求URL：/test/sw/{num}
请求方法：GET，这里说明下为什么要声明请求的方法，如果不声明请求的方法Swagger会默认的将同一个请求分别通过不同方式进行条目构建。
例如：请求为指明请求方法，Swagger会默认对该请求生成不同请求方法的条目。
@ApiOperation：注解中声明了请求的相关描述信息，重点是response，请求的返回值类型。这点需要注意。
这里采用了两种参数获取的方式，一种是通过@RequestParam取?param=value，一种是通过@PathVariable取URL中的{num}参数。
这里的参数名 str、num 必须要和@ApiImplicitParam中的name字段的值一致。paramType参数的配置，类比上述注解参数含义。对号入座。
测试请求：
预期请求URL：/test/sw/2333?str=hello
点击Try it out!
测试成功，Swagger支持多种类型的API测试，这里就是做了简单测试。Swagger还有很多DIY的功能，作为一个完善的API框架，可以进行定制化类似Python的web框架Django，根据需要就行页面定制等功能。
参考文档：
https://blog.csdn.net/xxoo00xx00/article/details/77163399