Spring boot整合Swagger2接口文档使用

背景：
最近进行项目优化，增添swagger功能方便接口测试！

一、SWAGGER简介

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

作用：

接口的文档在线自动生成。

功能测试。

Swagger是一组开源项目，其中主要要项目如下：

Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
Swagger-js: 用于JavaScript的Swagger实现。
Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

二、SPRINGBOOT整合流程

1.POM.XML中添加MAVEN依赖

此处需要注意的是版本问题，高版本的swagger必须对应高版本的springboot，我们项目集成的是 springboot1.5.9 + swagger2.2.2

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.2.2</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.2.2</version>
</dependency>

2.增加SWAGGERCONFIG配置类

/**
 * Swagger配置类
 * @Author: yuanj
 * @Date: 2018/9/17 13:43
 */
@Configuration
@EnableSwagger2
@ConditionalOnProperty(prefix = "msg-config", name = "swagger-open", havingValue = "true")
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.moerlong.service_authorize.controller"))    //这里采用包扫描的方式来确定要显示的接口
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("MoerService Gateway Doc")                       //标题
                .description("摩尔服务授权网关 Api文档")                  //描述
                .termsOfServiceUrl("http://www.moerlong.com")           //条款地址（不可见）
                .contact("moerlong")                                    //作者信息
                .version("1.0")                                         //版本号
                .build();
    }

}

注意此处使用了@ConditionalOnProperty标签，可以配合application.yml进行swagger的开关配置：

@ConditionalOnProperty(prefix = "msg-config", name = "swagger-open", havingValue = "true")

application.yml 中添加：

msg-config:
  swagger-open: true

其中name用来从application.yml中读取某个属性值，如果该值为空，则返回false;如果值不为空，则将该值与havingValue指定的值进行比较，如果一样则返回true;否则返回false。如果返回值为false，则该configuration不生效；为true则生效。

3.在CONTROLLER层添加相关注解

Swagger使用的注解及其说明：

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

@ApiOperation：注解来给API增加方法说明。

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

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

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

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiImplicitParam的参数说明：
在这里插入图片描述

注：paramType 必须与方法参数获取使用的注解一致，不然无法接受到参数值

实际案例：

@RestController
@RequestMapping("/teacher")
@Api(value = "UserController", description = "老师相关接口")
public class TeacherController {

    @Autowired
    private TeacherService teacherSvc;

    @OpenApi
    @RequestMapping(value = "findPage", method = RequestMethod.POST)
    @ApiOperation(value = "findPage", notes = "首页查询老师列表")
    public ResponseFindPage<TeacherResponse> findPage(@RequestBody TeacherSearchRequest body) {
        return teacherSvc.findPage(body);
    }

    @OpenApi
    @RequestMapping(value = "auth", method = RequestMethod.GET)
    @ApiOperation(value = "auth", notes = "鉴权")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "code", value = "code", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "encryptedData", value = "encryptedData", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "iv", value = "iv", required = true, dataType = "String")
    })
    public ResponseMessage<UserResponse> auth(@RequestParam String code, @RequestParam String encryptedData, @RequestParam String iv) {
        return userService.auth(code, encryptedData, iv);
    }
}