1.什么是Swagger2?

Swagger是一个RESTFUL 接口的文档在线自动生成和功能测试的框架。

Swagger 是一个规范和完整的框架。用于生成、描述、调用和可视化RestFul风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法、参数和模型紧密集成到服务器的代码，允许Api 来始终保持同步，Swagger让部署管理和使用功能强大的Api。

官网：http://swagger.io/

GIthub地址：https://github.com/swagger-api/swagger-ui

2.Swagger2的maven依赖

io.springfox

springfox-swagger2

2.2.2

io.springfox

springfox-swagger-ui

2.2.2

3.SwaggerConfig的配置

12.png

通过@Configuration注解，让SpringBoot来加载该类的配置，再通过@EnableSwagger2注解来启用Swagger2Config。

再通过buildDocket函数创建Docket的Bean之后。buildApiInfo() 用来创建该Api的基本信息(这些信息会展示在文档页面当中)。

select()函数返回一个ApiSelectBuilder实例来控制哪些接口来暴露给swagger2来展示，一般采用指定扫描的包路径来定义。

Swagger会扫描该包下的所有Controller定义的Api，并产生文档内容。(除了被@ApiIgnore指定的请求)。

4,。配置Controller中的Api

下面的内容是基于spring-boot进行配置的，不一定适用于所有的框架，

(1) 下面是常用的一些注解：

@Api: 用在类上，说明该类的作用。

@ApiOperation:用在方法上 ，说明该方法的作用，标注在具体的请求中，value和notes的作用差不多，都是对请求做以说明，tags 则是对请求进行分类的，比如说，你有好几个Controller，分别属于不同的功能模快，那么这里就可以用tags来分类的，

看上去条理性很好

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

paramType：参数放在哪个地方

header 请求参数的获取：@RequestHeader

query 请求参数的获取：@RequestParam

path(用于restful接口) 请求参数的获取：@PathVariable

body(不常用)

form(不常用)

name：参数名

dataType：参数类型

required：参数是否必须传

value：参数的意思

defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

code：数字，例如400

message：信息，例如"请求参数没填好"

response：抛出异常的类

@ApiModel：描述一个Model的信息(这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候)表明这是一个被swagger框架管理的model，用于class上

@ApiModelProperty 这里顾名思义，描述一个model的属性，就是标注在被标注了@ApiModel的class的属性上，这里的value是对字段的描述，example是取值例子，注意这里的example很有用，对于前后端开发工程师理解文档起到了关键的作用，因为会在api文档页面上显示出这些取值来；这个注解还有一些字段取值，可以自己研究，举例说一个：position，表明字段在model中的顺序。