簡介

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

 我們的RESTful API就有可能要面對多個開發人員或多個開發團隊：IOS開發、Android開發或是Web開發等。為了減少與其他團隊平時開發期間的頻繁溝通成本，傳統做法我們會建立一份RESTful API文件來記錄所有介面細節，然而這樣的做法有以下幾個問題：

  由於介面眾多，並且細節複雜（需要考慮不同的HTTP請求型別、HTTP頭部資訊、HTTP請求內容等），高質量地建立這份文件本身就是件非常吃力的事，下游的抱怨聲不絕於耳。
  隨著時間推移，不斷修改介面實現的時候都必須同步修改介面文件，而文件與程式碼又處於兩個不同的媒介，除非有嚴格的管理機制，不然很容易導致不一致現象。
 為了解決上面這樣的問題，本文將介紹RESTful API的重磅好夥伴Swagger2，它可以輕鬆的整合到Spring Boot中，並與Spring MVC程式配合組織出強大RESTful API文件。它既可以減少我們建立文件的工作量，同時說明內容又整合入實現程式碼中，讓維護文件和修改程式碼整合為一體，可以讓我們在修改程式碼邏輯的同時方便的修改文件說明。另外Swagger2也提供了強大的頁面測試功能來除錯每個RESTful API。具體效果如下圖所示：
 

新增Swagger2依賴

在pom.xml中加入Swagger2的依賴

<dependency>  
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>  
<dependency>  
    <groupId>io.springfox</groupId>
    <artifactId
 
>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>4.3.4.RELEASE</version>
    </dependency
 
>

或者
直接匯入包

注意：Spring 必須 4 以上
Jackson最好2.8

建立Swagger2配置類：

/**   
 * Swagger2構建RESTful APIs  
 * @author AndyBao  
 * @version 4.0, 2016年12月20日 下午2:00:30   
 */   
@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ybt.web.app"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("APP RESTful APIs")
                .description("線上文件：http://www.xxx.xxx")
                .termsOfServiceUrl("http://www.xxxx.com.cn/")
                .contact("AndyBao")
                .version("0.5.1")
                .build();
    }

}

如上程式碼所示，通過@Configuration註解，讓Spring來載入該類配置。再通過@EnableSwagger2註解來啟用Swagger2。

再通過createRestApi函式建立Docket的Bean之後，apiInfo()用來建立該Api的基本資訊（這些基本資訊會展現在文件頁面中）。select()函式返回一個ApiSelectorBuilder例項用來控制哪些介面暴露給Swagger來展現，本例採用指定掃描的包路徑來定義，Swagger會掃描該包下所有Controller定義的API，併產生文件內容（除了被@ApiIgnore指定的請求）。

新增文件內容

給Controller 添加註解
通過@ApiOperation註解來給API增加說明、通過@ApiImplicitParams、@ApiImplicitParam註解來給引數增加說明。

    /**
     * 引數描述
     *
     * @param userName
     * @return
     */
    @RequestMapping(value = "/demo2/{userName}", method = RequestMethod.POST)
    @ApiOperation(value = "測試介面2", notes = "引數描述", code = 200, produces = "application/json")
    public ModelMap getDemo2(@ApiParam(name = "userName", value = "編號", required = true) @PathVariable("userName") String userName) {
        ModelMap map = new ModelMap();
        map.addAttribute("userName", userName);
        return map;
    }

重啟web服務訪問：