Spring Boot 中配置 Swagger2

简单介绍
Spring Boot 是和 Spring 框架紧密结合用于提升 Spring 开发者体验的工具。它集成了大量的第三方库，在 Spring Boot 的基础上使用它们，基本可以做到零配置的开箱即用，所以使用 Spring Boot 开发，只需要配置很少的配置代码，非常适用于敏捷开发。
Swagger。前后端分离后，前端和后端人员通过接口进行协作。后台只负责数据的提供和计算，而完全不处理展现。而前端则负责拿到数据，组织数据并展现的工作。但是接口在开发过程中可能会产生变动，这样就会给前后端的集成增加成本。Swagger 就是在这个背景下产生的 API 设计工具。Swagger包括库、编辑器、代码生成器等很多部分，本篇文章主要介绍如何在 Spring Boot 中集成 Swagger。

应用背景
Spring Boot：1.4.0.RELEASE
Gradle：2.14
Swagger：springfox-swagger2:2.6.0
本文默认已配置好 Spring Boot、Gradle 环境

配置步骤
1. 在 Gradle 中添加 Swagger 依赖

//swagger
dependencies {
     ...
     compile "io.springfox:springfox-swagger2:2.6.0"
     compile 'io.springfox:springfox-swagger-ui:2.6.0'
     ...
}

1. 在 Spring Boot 的 Application.java 同级创建 Swagger2 的配置类 Swagger2。

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        ApiInfo apiInfo = apiInfo();
        Docket docket =  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .pathMapping("/")
                .directModelSubstitute(LocalDate.class,
                        Date.class)
                .useDefaultResponseMessages(false);
        if (!Objects.isNull(apiInfo)) {
            docket.apiInfo(apiInfo);
        }
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot + Gradle 使用 Swagger2 构建 API 文档")
                .description("项目描述")
.termsOfServiceUrl("https://hj.canmou123.com/")
                .contact("dreamhj")
                .version("1.0")
                .build();
    }
}

通过@Configuration注解，让Spring来加载Swagger配置，再通过@EnableSwagger2注解来启用Swagger2。@Bean 将createRestApi() 返回的Docket注册成Spring的Bean进行管理。
- apiInfo()用来自定义Api的基本信息
- select()选择那些路径和api会生成document
- apis(RequestHandlerSelectors.any()) 对所有api进行监控
- paths(PathSelectors.any()) 对所有路径进行监控

使用参数说明
1. Api：修饰整个类，描述Controller的作用
2. ApiOperation：描述一个类的一个方法，或者说一个接口
3. ApiParam：单个参数描述
4. ApiModel：用对象来接收参数
5. ApiProperty：用对象接收参数时，描述对象的一个字段
6. ApiImplicitParams、ApiImplicitParam：描述接口参数
7. ApiModel：传递复杂对象定义
8. ApiResponse：HTTP响应其中1个描述
9. ApiResponses：HTTP响应整体描述

注意：ApiImplicitParam 和 ApiParam 区别
1.对Servlets或者非 JAX-RS的环境，只能使用 ApiImplicitParam。
2.在使用上，ApiImplicitParam比ApiParam具有更少的代码侵入性，只要写在方法上就可以了，但是需要提供具体的属性才能配合swagger ui解析使用。
3.ApiParam只需要较少的属性，与swagger ui配合更好

demo
简单的列表接口功能描述

    @ApiOperation(value = "接口描述")
    @ApiImplicitParam(name = "接口参数名", value = "接口参数说明", required = true, dataType = "Integer", paramType = "query")
    @RequestMapping(path="/list", method = RequestMethod.GET)
    public ResponseEntity list(@RequestParam Integer pageNumber){...}