swagger 整合springmvc

一：引入下面的依賴

<!-- 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管理的依賴包不是具有傳遞性嗎？是的，是有傳遞性，但是傳遞性是根據來界定的。打開swagger-springmvc依賴包的pom文件可以發現，其很多依賴包的scope值爲compile或者provider，不會根據傳遞性自動引入。

二：swagger配置
新建一個類代碼如下：

package com.chltec.vendor.config;

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.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

@Configuration
@EnableSwagger
@EnableWebMvc
@ComponentScan(basePackages = {
        "com.chltec.vendor.controller" })
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;
        //訪問地址；http://localhost:8080/swagger/index.html   swagger-ui2.0版本可以出現界面。swagger-ui3.0版本會出現No operations defined in spec
    }

}

SpringSwaggerConfig無法注入。因爲spring容器裏沒有SpringSwaggerConfig類型的對象。解決辦法：在springmvc的配置文件中加入以下配置即可。

  到目前爲止，我們已經完成了對所有接口方法的掃描解析功能，那解析得到什麼內容呢？這需要我們自定義，自定義操作的對象就是接口方法。先看段代碼：
  /**
* 根據用戶名獲取用戶對象
* @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對象");
}

}

 @RequestMapping(value = "/updatePassword", method = RequestMethod.POST)
    @ResponseBody
    public ResponseEntity<BaseResponse> updatePassword(@RequestParam("old_password") String old_password,@RequestParam("new_password") String new_password,@RequestParam("confirm_password") String confirm_password,@RequestParam("phone_number") String phone_number){
        Agent agent =agentService.findByPhoneNumber(phone_number);
        if(agent==null){
            return new ResponseEntity<BaseResponse>(new BaseResponse(ResponseCode.NO_REGISTER), HttpStatus.OK);
        }else {
        ......
    }

  上述代碼是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。http://localhost:8080/swagger/index.html

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

//所有swagger目錄的訪問，直接訪問location指定的目錄

  以下爲接口文檔形式圖：

注：swagger最好用2.0版本，3.0會出現No operations defined in spec問題。

參考文章：http://www.cnblogs.com/jtlgb/p/6734177.html