Restful形式接口文檔生成之Swagger與SpringMVC整合手記

      筆者目前正在搭建一套API服務框架，考慮到客戶端可以更方便的調用API服務（這裏說的更方即是指避免不厭其煩地解說各接口須要的參數和返回結果），因而決心爲每一個接口生成詳細的說明文檔。網上搜索了一下，發現了Swagger這個東西，感受不錯，界面也比javadoc生成的頁面要美觀，並且網上關於Swagger和springmvc整合的文章很多（遺憾的是大多雷同且不完整）。本文詳細介紹Swagger和SpringMVC的整合過程，重點是彌補現有文章的遺漏之處（很關鍵的哦！）。讓咱們一塊兒來學習如何使用Swagger來生成接口文檔吧！

  既然是整合Swagger，那麼前提是你已經使用SpringMVC搭建了一套接口服務，不管繁簡，只要可用就行。關於接口文檔生成工具，你們在網上搜索的時候，可能會發現另一個工具：springfox。網上關於springfox和spring整合的文章也很是多的呀。那springfox和swagger是什麼關係呢？引用springfox官方的語錄：

Springfox has evolved from a project originally created by Marty Pitt and was named swagger-springmvc.

  這段英文很簡單，不懂的讀者對照在線詞典也能夠翻譯出來，加油！言歸正傳，先簡單介紹下項目環境：

• JDK1.7
• Spring 3.2.2
• swagger-springmvc 1.0.2 （最新版本）

1、依賴管理

  在整合以前，須要把全部使用到的依賴包所有引入。網上不少文章只是簡單告訴讀者引入swagger-springmvc-1.0.2.jar包，可是隨後你發現這遠遠不夠，還須要不少包，以下所示：

<!-- swagger-springmvc -->
    <dependency>
        <groupId>com.mangofactory</groupId>
        <artifactId>swagger-springmvc</artifactId>
        <version>1.0.2</version>
    </dependency>
    <dependency>
        <groupId>com.mangofactory</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.0.2</version>
    </dependency>
    <dependency>
        <groupId>com.wordnik</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.3.11</version>
    </dependency>
    <!-- swagger-springmvc dependencies -->
    <dependency>
        <groupId>com.google.guava</groupId>
        <artifactId>guava</artifactId>
        <version>15.0</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-annotations</artifactId>
        <version>2.4.4</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.4.4</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-core</artifactId>
        <version>2.4.4</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml</groupId>
        <artifactId>classmate</artifactId>
        <version>1.1.0</version>
    </dependency>

  以上是比較完整的依賴列表，本文搭建的項目能夠正常運行。讀者可能會有疑問，maven管理的依賴包不是具備傳遞性嗎？是的，是有傳遞性，可是傳遞性是根據<scope>來界定的。打開swagger-springmvc依賴包的pom文件能夠發現，其不少依賴包的scope值爲compile或者provider，不會根據傳遞性自動引入。

2、Swagger配置

  Swagger的配置實際上就是自定義一個Config類，經過java編碼的方式實現配置。代碼以下：

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * Created by xiaohui on 2016/1/14.
 */
@Configuration
@EnableSwagger
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    /**
     * Required to autowire SpringSwaggerConfig
     */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
    {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    /**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation()
    {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*?");
    }

    private ApiInfo apiInfo()
    {
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title",
                "My Apps API Description",
                "My Apps API terms of service",
                "My Apps API Contact Email",
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }
}

  上面這段代碼是從網絡上找到的，你也確定找到了，對吧！可是，你會發現一個問題：SpringSwaggerConfig沒法注入。這是爲何呢？其實很簡單，由於spring容器裏沒有SpringSwaggerConfig類型的對象。解決辦法：在springmvc的配置文件中加入如下配置便可。

<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

  到目前爲止，咱們已經完成了對全部接口方法的掃描解析功能，那解析獲得什麼內容呢？這須要咱們自定義，自定義操做的對象就是接口方法。先看段代碼：

/**
 * 根據用戶名獲取用戶對象
 * @param name
 * @return
 */
@RequestMapping(value="/name/{name}", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "根據用戶名獲取用戶對象", httpMethod = "GET", response = ApiResult.class, notes = "根據用戶名獲取用戶對象")
public ApiResult getUserByName(@ApiParam(required = true, name = "name", value = "用戶名") @PathVariable String name) throws Exception{
    UcUser ucUser = ucUserManager.getUserByName(name);

    if(ucUser != null) {
        ApiResult<UcUser> result = new ApiResult<UcUser>();
        result.setCode(ResultCode.SUCCESS.getCode());
        result.setData(ucUser);
        return result;
    } else {
        throw new BusinessException("根據{name=" + name + "}獲取不到UcUser對象");
    }
}

  上述代碼是Controller中的一個方法，@ApiOperation註解對這個方法進行了說明，@ApiParam註解對方法參數進行了說明。關於這兩個註解的使用，能夠參看源碼。這樣子，Swagger就能夠掃描接口方法，獲得咱們自定義的接口說明內容。

3、Swagger-UI配置

  Swagger掃描解析獲得的是一個json文檔，對於用戶不太友好。下面介紹swagger-ui，它可以友好的展現解析獲得的接口說明內容。

  從https://github.com/swagger-api/swagger-ui 獲取其全部的 dist 目錄下東西放到須要集成的項目裏，本文放入 src/main/webapp/WEB-INF/swagger/ 目錄下。

  修改swagger/index.html文件，默認是從鏈接http://petstore.swagger.io/v2/swagger.json獲取 API 的 JSON，這裏須要將url值修改成http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根據自身狀況填寫。好比個人url值爲：http://localhost:8083/arrow-api/api-docs

  由於swagger-ui項目都是靜態資源，restful形式的攔截方法會將靜態資源進行攔截處理，因此在springmvc配置文件中須要配置對靜態文件的處理方式。

//全部swagger目錄的訪問，直接訪問location指定的目錄
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

  OK！大功告成，打開瀏覽器直接訪問swagger目錄下的index.html文件，便可看到接口文檔說明了。注意訪問地址哦！看下圖：

文章做者：xiaohui249
本文連接：http://javatech.wang/index.php/archives/74/ 版本全部 ©轉載時必須以連接形式註明做者和原始出處