Springfox與swagger的整合使用

1、前言

讓咱們先理一下springfox與swagger的關係。

swagger是一個流行的API開發框架，這個框架以「開放API聲明」（OpenAPI Specification，OAS）爲基礎，對整個API的開發週期都提供了相應的解決方案，是一個很是龐大的項目（包括設計、編碼和測試，幾乎支持全部語言）。

OAS自己是一個API規範，它用於描述一整套API接口，包括一個接口是GET仍是POST請求啊，有哪些參數哪些header啊，都會被包括在這個文件中。它在設計的時候一般是YAML格式，這種格式書寫起來比較方便，而在網絡中傳輸時又會以json形式居多，由於json的通用性比較強。

因爲Spring的流行，Marty Pitt編寫了一個基於Spring的組件swagger-springmvc，用於將swagger集成到springmvc中來。而springfox則是從這個組件發展而來，同時springfox也是一個新的項目，本文仍然是使用其中的一個組件springfox-swagger2。

pringfox-swagger2依然是依賴OSA規範文檔，也就是一個描述API的json文件，而這個組件的功能就是幫助咱們自動生成這個json文件，咱們會用到的另一個組件springfox-swagger-ui就是將這個json文件解析出來，用一種更友好的方式呈現出來。

這是入門，咱們簡單地介紹springfox-swagger2的配置，幫助各位順利地實現使用，文中有不少本身的理解，如有錯誤，歡迎批評指正。

2、配置流程說明

在開始編碼以前，咱們先對配置的流程有個大體的瞭解。

在前言中，咱們知道，咱們的第一個任務就是生成一個知足OSA規範的json文件（固然，建立一個spring的項目就不說了）。對於這個任務，springfox爲咱們提供了一個Docket（摘要的意思）類，咱們須要把它作成一個Bean注入到spring中，顯然，咱們須要一個配置文件，並經過一種方式（顯然它會是一個註解）告訴程序，這是一個Swagger配置文件。

一個OSA規範文檔須要許多信息來描述這個API，springfox容許咱們將信息組合成一個ApiInfo的類，做爲構造參數傳給Docket（固然也能夠不構造這個類，而直接使用null，可是你的這個API就太low了）。

接下來，咱們要寫控制器了，固然這不重要，不用springfox你依然要寫控制器，重要的是要告訴springfox，這個控制器是一個須要他來收集API信息的控制器，不用說，這依然會採用註解的方式，同時，咱們爲了將配置文件與控制器結合起來，須要在配置文件中指明在什麼位置收集多是API的控制器的信息。

到這裏，生成OSA規範的json文件的配置就結束了。雖然生成過程比我敘述的更復雜，但這些程序都會幫咱們完成，咱們能夠經過相似http://localhost:8080/demo/v2/api-docs的路徑來查看這個json文件。這個v2/api-docs就是springfox默認的生成文檔的路徑。

接下來，咱們須要將它可視化顯示出來，若是使用swagger-springmvc，咱們須要單獨去下載一個swagger ui的顯示頁面包，並將其中的路徑改成上面的http://localhost:8080/demo/v2/api-docs，這裏你就能夠感覺到，swagger ui就是在解析一個json文件了。你依然能夠這麼作，不過springfox專門提供了一個springfox-swagger-ui組件，不須要配置，咱們只須要引入這個依賴的組件就能夠看到最終的效果了，而這個路由會是http://localhost:8080/demo/swagger-ui.html。

3、引入依賴

若是我寫的不錯，相信看到這裏，你就大體瞭解了springfox swagger2的使用流程了。那麼，咱們進入正式編碼的第一步：引入依賴。

這裏咱們使用maven引入依賴，你們能夠到http://mvnrepository.com上搜索springfox，即可以看到Springfox Swagger2和Springfox Swagger Ui，而後就能夠從中獲取最新的資源了。以下：

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.7.0</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.7.0</version>

</dependency>

 

此外還須要一個依賴組件：

<dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.6.6</version>
</dependency>

 

4、一個簡單的配置文件

爲了清晰，咱們能夠先在經常使用的源碼包裏建一個config目錄，並在裏面建立一個SwaggerConfig.java文件，這是一個spring的配置文件，因此位置和文件名都影響不大。

先上代碼（這裏參考了博客http://blog.csdn.net/u012476983/article/details/54090423）：

@Configuration //必須存在
@EnableSwagger2 //必須存在
@EnableWebMvc //必須存在
@ComponentScan(basePackages = {"com.xiaoming.SpringMVC.controller"}) //必須存在 掃描的API Controller package name 也能夠直接掃描class (basePackageClasses)
public class SwaggerConfig{
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("小明", "http://www.cnblogs.com/getupmorning/", "zhaoming0018@126.com");
        return new ApiInfoBuilder()
                .title("前臺API接口")
                .description("前臺API接口")
                .contact(contact)
                .version("1.1.0")
                .build();
    }
}

 

因爲各位確定用的是IDE，這裏就不寫各類import了。

首先，這個SwaggerConfig類有四個註解，看名稱就能夠明白是什麼意思。其中，@Configuration，@EnableWebMvc和@ComponentScan是Spring的註解，而@EnableSwagger2則是用來啓動Swagger支持，表示這是一個Spring Swagger的配置文件。

以後，定義了一個Bean方法CustomDocket，Spring中名字並不重要，重要的是它返回一個Docket類，DocumentationType.SWAGGER_2做爲Docket構造方法的參數，指定了所用的swagger版本2.0，官網上已經在預告3.0版本了。而以後的apiInfo則是調用接下來的apiInfo函數，來建立Docket的信息。apiInfo函數採用ApiInfoBuilder來建立ApiInfo類。

5、一個控制器

其實，控制器不須要配置，就已經會被springfox swagger識別了，不過咱們這裏象徵性地加上一個描述信息：

@Controller
@RequestMapping("/test")
public class TestController {
    @ApiOperation(value="一個測試API",notes = "第一個測試api")
    @ResponseBody
    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    public String hello()
    {
        return "hello";
    }
}

 

這裏僅僅多了一個@ApiOperation註解，別的和一個普通的springmvc的控制器徹底一致。

實際上，爲了造成一個完整的api文檔，須要添加的註解經常不少，如果都寫在同一個文件裏就會顯得臃腫，咱們經常會寫一個接口文件，將註解都放在接口文件中，而後再用一個實體類來實現控制器，算是實現配置和邏輯分離了吧。

6、查看接口文件和文檔

如果沒有問題，如今能夠部署項目，並打開http://localhost:8080/demo/v2/api-docs：

 

 

Firefox提供了查看JSON的插件，推薦你們搜索試試看。

廢話很少說，這裏能夠看到以前配置的諸多信息。注入description，version，title等。而且確實有TestController的信息。

最後，咱們打開http://localhost:8080/swagger-ui.html，即可以看到一個漂亮的界面了：