Swagger

一、集成

1、Maven 坐标

    //Swagger 2 的核心依赖
	<dependency>
	  <groupId>io.springfox</groupId>
	  <artifactId>springfox-swagger2</artifactId>
	  <version>2.6.1</version>
	</dependency>
	//Swagger-UI 的依赖,Swagger 的 API 管理界面
	<dependency>
	  <groupId>io.springfox</groupId>
	  <artifactId>springfox-swagger-ui</artifactId>
	  <version>2.6.1</version>
	</dependency>

2、配置 Swagger-UI

在对 Swagger-UI 进行配置时只需要使用两个注解和一个配置类即可完成，SpringBoot 为我们提供了两种配置方法：

1. Swagger-UI 集成注解与配置类分开配置
   （1）在启动类上添加注解 @EnableSwagger2
   （2）新建一个配置类，并在该配置类上添加 @Configuration 注解
2. Swagger-UI 集成注解与配置类集中配置
   创建Swagger2Config类，添加 @EnableSwagger2和 @Configuration注解

两者区别：
第一种方式， @EnableSwagger2 注解的声明没有通过 @Configuration 注解来处理，而是通过 SpringBoot 应用去自动装配；
第二种方式则是将配置类和 Swagger-UI 的所有注解都通过 @Configuration 注解来处理，不通过 SpringBoot 应用去自动装配。

3、Swagger-UI 配置类详解

创建配置类Swagger2Config

@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.allen.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("demo text API")
                .description("测试-扩展 API")
                .contact(new Contact("allen", "", ""))
                .version("1.0")
                .build();
    }
}

代码解释：
（1）createRestApi

1. createRestApi 方法的返回值是一个 Docket 类型，该类型就是返回 Documentation 类型的数据。
2. 在方法内部，使用匿名内部类的方式实例化了一个 Docket 对象并返回，DocumentationType
   即文档类型的选择我们需要根据集成的 Swagger 的版本来选择，这里选择 SWAGGER_2 表示使用的 Swagger是2.X系列版本。
3. apiInfo() 和 select() 这两个方法是配置 Swagger 应用的必要方法，我们只需要这样理解就可以了：集成必要的 API 信息（apiInfo() 方法）来供我们查询（select() 方法）使用。
4. apis() 方法里面通过 RequestHandlerSelectors.basePackage() 属性来描述我们要扫描的目标包。
5. paths() 方法就是将项目中所有接口的请求路径都暴露给 Swagger 来生成 Swagger-UI 界面。
6. build() 方法就是将设置的上述参数都放到返回的 Docket 实例中。

（2）apiInfo

1. title() 方法：就是来规定我们的 Swagger-UI 界面的大标题。
2. description() 方法：就是来规定对 Swagger-UI 界面的一些简单描述信息。
3. contact() 方法：就是来规定创建 Swagger-UI 的作者的名称。
4. version() 方法：就是来规定 Swagger-UI 界面上所有接口的版本。
5. build() 方法：就是将我们设置的上述参数都放到返回的 ApiInfo 实例中。
   

二、注解@ApiOperation

1、什么是 ApiOperation

为了方便知道这些接口的功能作用，需要给接口添加一些具体的描述信息，为此，在 Swagger 中，我们就需要使用 ApiOperation 注解来描述我们写的接口。
ApiOperation 注解提供了丰富的属性来允许我们自定义接口描述信息，包括接口名称，接口所属分组等。

2、属性

3、属性详解

（1）value

该属性就是描述接口的作用是什么

    @ApiOperation(value = "查询信息")
    @GetMapping("/emp/{id}")
    public Employee getEmp(@PathVariable("id") Integer id){
        return employeeService.getEmpById(id);
    }

（2）tags

该属性就是对实现相同业务场景的接口做一个分组。

@ApiOperation(value = "查询信息", tags = "emp")
    @GetMapping("/emp/{id}")
    public Employee getEmp(@PathVariable("id") Integer id){
        return employeeService.getEmpById(id);
    }

当接口涉及多个业务时，接口进行多个分组

    @ApiOperation(value = "查询信息", tags = {"emp", "customer"})
    @GetMapping("/emp/{id}")
    public Employee getEmp(@PathVariable("id") Integer id){
        return employeeService.getEmpById(id);
    }

（3）notes

该属性就是对接口方法做进一步详细的描述。

    @ApiOperation(value = "查询信息", tags ="emp", notes = "查询信息必须是get请求")
    @GetMapping("/emp/{id}")
    public Employee getEmp(@PathVariable("id") Integer id){
        return employeeService.getEmpById(id);
    }

（4）httpMethod 和 nickname

httpMethod () 属性就是对接口的请求类型进行一个约定，常用的接口类型有：“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS”。
nickname () 属性是为接口起一个别名，方便前后端沟通使用。我们设置的别名会出现在浏览器地址栏中

@ApiOperation(value = "查询信息", tags ="emp", notes = "查询信息必须是get请求",
    nickname = "empNickName", httpMethod = "GET")
    @GetMapping("/emp/{id}")
    public Employee getEmp(@PathVariable("id") Integer id){
        return employeeService.getEmpById(id);
    }

三、@Api

Api 是作用在类上面的注解，其主要是用来给接口类定义相关说明。

@Api(value = "eee-controller", tags = "emptags")
@RestController
public class EmployeeController {

四、@ApiParam

1、定义

ApiParam 注解，是可以作用在 接口方法上面，以及 接口方法中的参数位置的注解，其主要是用来给接口中的参数定义相关参数说明，主要是为了帮助理解接口中每个参数的含义。

2、属性

3、属性详解

（1）name
该属性就是描述接口中参数的名称。

	@ApiParam(name = "id")
    @ApiOperation(value = "查询信息", tags = "emp1", notes = "查询类型get")
    @GetMapping("/emp/{id}")
    public Employee getEmp(@PathVariable("id") Integer id){
        return employeeService.getEmpById(id);
    }

（2）value
该属性就是对接口中的参数做一个简要的描述

	@ApiParam(name = "id", value = "主键ID")
    @ApiOperation(value = "查询信息", tags = "emp1", notes = "查询类型get")
    @GetMapping("/emp/{id}")
    public Employee getEmp(@PathVariable("id") Integer id){
        return employeeService.getEmpById(id);
    }

 注意：红色框内没有显示写的value值，仍是默认值

如何展示value值，将@ApiParam放到参数中，Parameter和Description就会显示我们想要的值

	@ApiOperation(value = "查询信息", tags = "emp1", notes = "查询类型get")
    @GetMapping("/emp/{id}")
    public Employee getEmp(@ApiParam(name = "ID", value = "主键ID") Integer id){
        return employeeService.getEmpById(id);
    }

（3）required
该属性就是对接口方法中参数传递的必要性做一个约定，即接口方法中的参数哪些是必须传递的，哪些是非必须传递的

	@ApiOperation(value = "查询信息", tags = "emp1", notes = "查询类型get")
    @GetMapping("/emp/{id}")
    public Employee getEmp(@ApiParam(value = "主键ID", required = true) Integer id){
        return employeeService.getEmpById(id);
    }

五、 @ApiImplicitParam注解

1、定义

ApiImplicitParam 注解是作用在接口方法上的注解，用来对该接口中的参数进行简短的描述，常常和 ApiParam 注解一起搭配使用。

2、属性

3、属性详解

（1）name
该属性就是描述接口中参数的名称。

	@ApiOperation(value = "查询信息", tags = "emp1", notes = "查询类型get")
    @ApiImplicitParam(name = "参数ID")
    @GetMapping("/emp/{id}")
    public Employee getEmp(@ApiParam(name = "id", value = "主键ID") Integer id){
        return employeeService.getEmpById(id);
    }

（2）value()
value属性就是对接口方法中的参数，进行简单必要的描述。
defaultValue() 属性就是定义接口方法中参数的默认值。

   @ApiOperation(value = "查询信息", tags = "emp1", notes = "查询类型get")
    @ApiImplicitParam(name = "参数ID", value = "参数值主键ID")
    @GetMapping("/emp/{id}")
    public Employee getEmp(@ApiParam(name = "id", value = "主键ID") Integer id){
        return employeeService.getEmpById(id);
    }

六、@ApiModel 和 @ApiModelProperty

1、定义

ApiModel 注解是作用在实体类上的注解，用来对该接口相关实体类添加额外的描述信息，常常和 @ApiModelProperty 注解配合使用。

ApiModelProperty 注解是作用在实体类的参数上的注解，用来对具体的实体类中的参数添加额外的描述信息，常常和 @ApiModel 注解关联使用，有时也会单独拿出来用。

2、属性

@ApiModel(value = "雇佣实体", description = "雇佣实体中包含用户相关的所有业务字段")
public class Employee implements Serializable {
    private Integer id;
    @ApiModelProperty(value = "姓名", required = true)
    private String lastName;

七、@ApiResponse 和 @ApiResponses

1、定义

ApiResponse 注解是作用在接口方法上的注解，用来对该接口方法的一个或多个返回值进行描述，一般不会单独使用，常常和 @ApiResponses 注解配合使用。

2、属性