Springfoxhas evolved from a project originally created by Marty Pitt and was namedswagger-springmvc.
這段英文很簡單，不懂的讀者對照在線詞典也可以翻譯出來，加油！言歸正傳，先簡單介紹下項目環境：
-
JDK1.7
-
Spring 3.2.2
-
swagger-springmvc 1.0.2 （最新版本）
在整合之前，需要把所有使用到的依賴包全部引入。網上很多文章只是簡單告訴讀者引入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的配置實際上就是自定義一個Config類，通過Java編碼的方式實現配置。代碼如下：
importcom.mangofactory.swagger.configuration.SpringSwaggerConfig;
importcom.mangofactory.swagger.models.dto.ApiInfo;
importcom.mangofactory.swagger.plugin.EnableSwagger;
importcom.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
importorg.springframework.beans.factory.annotation.Autowired;
importorg.springframework.context.annotation.Bean;
importorg.springframework.context.annotation.Configuration;
/**
* Created by xiaohui on 2016/1/14.
*/
@Configuration
@EnableSwagger
publicclass SwaggerConfig {
private SpringSwaggerConfigspringSwaggerConfig;
/**
* Required to autowire SpringSwaggerConfig
*/
@Autowired
public voidsetSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
{
this.springSwaggerConfig = springSwaggerConfig;
}
/**
* Every SwaggerSpringMvcPlugin bean ispicked up by the swagger-mvc
* framework - allowing for multipleswagger groups i.e. same code base
* multiple swagger resource listings.
*/
@Bean
public SwaggerSpringMvcPlugincustomImplementation()
{
return newSwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.includePatterns(".*?");
}
private ApiInfo apiInfo()
{
ApiInfo apiInfo = new ApiInfo(
"My Apps API Title",
"My Apps APIDescription",
"My Apps API terms ofservice",
"My Apps API ContactEmail",
"My Apps API LicenceType",
"My Apps API LicenseURL");
return apiInfo;
}
}
上面這段代碼是從網絡上找到的，你也肯定找到了，對吧！但是，你會發現一個問題：SpringSwaggerConfig無法注入。這是爲什麼呢？其實很簡單，因爲spring容器裏沒有SpringSwaggerConfig類型的對象。解決辦法：在springmvc的配置文件中加入以下配置即可。
<beanclass="com.mangofactory.swagger.configuration.SpringSwaggerConfig"/>
到目前爲止，我們已經完成了對所有接口方法的掃描解析功能，那解析得到什麼內容呢？這需要我們自定義，自定義操作的對象就是接口方法。先看段代碼：
/**
* 根據用戶名獲取用戶對象
* @param name
* @return
*/
@RequestMapping(value="/name/{name}",method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value= "根據用戶名獲取用戶對象",httpMethod = "GET", response = ApiResult.class, notes = "根據用戶名獲取用戶對象")
publicApiResult getUserByName(@ApiParam(required = true, name = "name",value = "用戶名")@PathVariable String name) throws Exception{
UcUser ucUser =ucUserManager.getUserByName(name);
if(ucUser != null) {
ApiResult<UcUser> result = newApiResult<UcUser>();
result.setCode(ResultCode.SUCCESS.getCode());
result.setData(ucUser);
return result;
} else {
throw new BusinessException("根據{name=" + name + "}獲取不到UcUser對象");
}
}
上述代碼是Controller中的一個方法，@ApiOperation註解對這個方法進行了說明，@ApiParam註解對方法參數進行了說明。關於這兩個註解的使用，可以參看源碼。這樣子，Swagger就可以掃描接口方法，得到我們自定義的接口說明內容。
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:resourcesmapping="/swagger/**" location="/WEB-INF/swagger/"/>
OK！大功告成，打開瀏覽器直接訪問swagger目錄下的index.html文件，即可看到接口文檔說明了。注意訪問地址哦！看下圖：
常見的問題
-
問題1：下載maven的jar包中途失敗，工程會出錯maven missing
解決方法：選中Project->右鍵maven->update project->選中Forceupdate 如果此時依然有
missing的jar，按照 buildpath 提示的jar包missing 路徑，去 maven
本地倉庫中對應位置（jar包後面有路徑），刪掉 該 jar 包的xxx.lastUpdated 文件，之後，再重新執行
項目右鍵maven->update project -
問題2：缺失jackson包會導致出現異常java.lang.NoClassDefFoundError:
com/fasterxml/jackson/databind/ObjectMapper) -
問題3：java.lang.ClassNotFoundException:
org.springframework.web.util.Log4jConfigListen，因爲工程沒有引入maven中的jar包，解決辦法：選中工程右鍵->Properties->Deployment Assembly->add->Java BuildPath Entries->Maven Dependencies->OK -
問題4：org.springframework.beans.factory.BeanCreationException，出現這個異常是因爲SpringSwaggerConfig的私有成員RequestMappingHandlerMapping造成的，將
<mvc:annotation-driven />放入到web.xml的context-param標籤對應的配置文件application-config.xml中，完美解決，官網解釋該標籤作用爲： Required so swagger-springmvc can access spring’sRequestMappingHandlerMapping 。
