背景：
最近進行專案優化，增添swagger功能方便介面測試！

一、swagger簡介

Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，引數和模型緊密整合到伺服器端的程式碼，允許API來始終保持同步。

作用：

1. 介面的文件線上自動生成。
2. 功能測試。

Swagger是一組開源專案，其中主要要專案如下：

Swagger-tools:提供各種與Swagger進行整合和互動的工具。例如模式檢驗、Swagger 1.2文件轉換成Swagger 2.0文件等功能。
Swagger-core

二、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地址