Swagger與SpringMVC整合

依賴管理

  在整合之前，需要把所有使用到的依賴包全部引入。網上很多文章只是簡單告訴讀者引入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，不會根據傳遞性自動引入。

二、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
@EnableWebMvc
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就可以掃描接口方法，得到我們自定義的接口說明內容。

     說明： 
     其中@ApiOperation和@ApiParam為添加的API相關注解，個參數說明如下： 
     @ApiOperation(value = “接口說明”, httpMethod = “接口請求方式”, response = “接口返回參數類型”, notes = “接口發布說明”；其他參數可參考源碼； 
     @ApiParam(required = “是否必須參數”, name = “參數名稱”, value = “參數具體描述”

三、Swagger-UI配置

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

  從https://github.com/swagger-api/swagger-ui 獲取3.0版本以下，2.0版本以上。其所有的 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文件，即可看到接口文檔說明了。注意訪問地址哦！看下圖：