springboot项目整合swagger全过程

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

---

一、swagger简介

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

作用：

1. 接口的文档在线自动生成。
2. 功能测试。

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 必须与方法参数获取使用的注解一致，不然无法接受到参数值

实际案例：

**
 * 服务授权网关入口
 * @Author: yuanj
 * @Date: 2018/9/7 10:15
 */
@RestController
@RequestMapping("/moerService")
@Api(value = "Access-Controller", description = "服务授权网关")
public class AccessController {

    @RequestMapping(value = "/access", method = RequestMethod.POST)
    @ApiOperation(value = "入口方法", notes = "将token、apiCode、version、businessParams组合为Map(Json)类型参数")
    @ApiImplicitParam(paramType = "body", name = "params", value = "组合参数", required = true, dataType = "Map(Json)")
    public Result access(@RequestBody Map params) throws Exception {
       ......
    }


    @RequestMapping(value = "/test", method = RequestMethod.GET)
    @ApiOperation(value = "测试方法", notes = "模拟用户访问")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "token", value = "令牌", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "name", value = "客户姓名", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "idCard", value = "客户身份证", required = true, dataType = "String")
    })
    public String test(@RequestParam(value = "token",required = true) String token,
                       @RequestParam(value = "name",required = true) String name,
                       @RequestParam(value = "idCard",required = true) String idCard) {
        ......
    }
}

4.访问swagger地址

默认地址：http://localhost:8885/swagger-ui.html