一直苦於文檔整理工作，因為這是一個很無聊的工作，偶然在網上看到了swagger這東西，感覺不錯，於是動手集成了一下，眼前一亮
Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。
費話少說，下面來看一下集成的過程，我用的環境是：jdk1.8+tomcat7.0+springmvc4.2+maven3.0
1.首先,通過maven將相關的jar引入項目
<!-- swagger -->
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.dataformat</groupId>
<artifactId>jackson-dataformat-xml</artifactId>
<version>2.7.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.7.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.7.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.7.4</version>
</dependency>
<!-- swagger -->
2.寫一個自定義的swagger的config類
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; 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; /** * <B>文件名稱：</B>SwaggerConfig.java<BR> * <B>文件描述：</B><BR> * * <B>版權聲明：</B>(C)2014-2015<BR> * <B>公司部門：</B><BR> * <B>創建時間：</B>2016年6月30日<BR> * * @author * @version */ @Configuration @EnableWebMvc @EnableSwagger @ComponentScan("cn.brandwisdom.roomVouchers") public class SwaggerConfig { private SpringSwaggerConfig springSwaggerConfig; @Autowired public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) { this.springSwaggerConfig = springSwaggerConfig; } /** * 鏈式編程 來定制API樣式 * 后續會加上分組信息 * * @return */ @Bean public SwaggerSpringMvcPlugin customImplementation() { return new SwaggerSpringMvcPlugin(this.springSwaggerConfig) .apiInfo(apiInfo()) .includePatterns(".*") .apiVersion("0.0.1"); //.swaggerGroup(PROJECT_NAME); } 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; } }
3.將這個類交給spring來進行管理
<bean class="cn.brandwisdom.roomVouchers.swagger.SwaggerConfig"/>
4.通過注解的方式，讓swagger能夠知道我們接口對應的功能說明
@Controller @RequestMapping(value = "/user") @Api(value = "user") public class UserController { /** * 根據用戶名獲取用戶對象 * @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對象"); } } }
說明：@API(value="user")這個是用來分組的，（不過貌似不寫也可以，會自動根據controller來進行分組），@ApiOperation注解對這個方法進行了說明，@ApiParam注解對方法參數進行了說明。
4.Swagger-UI配置
Swagger掃描解析得到的是一個json文檔，對於用戶不太友好。下面介紹swagger-ui，它能夠友好的展示解析得到的接口說明內容。
從https://github.com/swagger-api/swagger-ui 獲取其所有的 dist 目錄下東西放到需要集成的項目里，本文放入 src/main/webapp/api/ 目錄下(也可以放到其它目錄下)。
修改index.html文件，默認是從連接http://petstore.swagger.io/v2/swagger.json獲取 API 的 JSON，這里需要將url值修改為http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根據自身情況填寫。比如我的url值為：http://localhost:8080/vouchers/api-docs
這里最好新建一個src/main/webapp/api-docs/目錄，用於程序生成接口對就的json文件，我看網上的人都沒有手動建，但是我的沒有自動生成，如果你們自動生成了，可以跳過這一步。
因為swagger-ui項目都是靜態資源，restful形式的攔截方法會將靜態資源進行攔截處理，所以在springmvc配置文件中需要配置對靜態文件的處理方式（我這里對目錄下所有文件全部放行了）。
<mvc:resources mapping="/api/**" location="/api/" />
OK！大功告成，打開瀏覽器直接訪問swagger目錄下的index.html文件，即可看到接口文檔說明了。注意訪問地址哦！我的訪問地址是：http://localhost:8080/vouchers/api/，注意，如果你web.xml沒有配置默認歡迎頁面，你要加index.html訪問。
項目中遇到了如下問題，參考了http://www.cnblogs.com/xmplatform/p/5785065.html
1、如何漢化/顯示中文
swagger-ui本身是支持多語言的，在index.html中有這么一段代碼：
<!-- Some basic translations --> <!-- <script src='lang/translator.js' type='text/javascript'></script> --> <!-- <script src='lang/ru.js' type='text/javascript'></script> --> <!-- <script src='lang/en.js' type='text/javascript'></script> -->
大家只需要把注釋打開，同時加入對應的中文js即可，最終修改如下：
<!-- Some basic translations --> <script src='lang/translator.js' type='text/javascript'></script> <script src='lang/zh-cn.js' type='text/javascript'></script> <!-- <script src='lang/en.js' type='text/javascript'></script> -->
2、在swagger-ui中默認的參數的Content Type是application/json，測試時發現后台參數沒有接收到值，怎么辦？
大家可能會問，Content Type是application/json有什么影響，為什么要修改為其他呢？這里就要涉及到springMVC中將請求傳遞過來的參數注入到Controller方法對應對象的原理了，具體知識大家可以搜索一下，這個不是本文重點我就不多講了，其實我們通常寫的Controller方法，默認的Content Type其實是application/x-www-form-urlencoded，而swagger中參數的默認Content Type是application/json，這樣就會導致使用swagger測試時，提交到Controller方法的對應參數無法正確注入。
- 那么，該如何處理呢，能改成其他嗎？
其實在swagger-ui的Issues中有人提到過，https://github.com/swagger-api/swagger-ui/issues/658，解決的辦法就是要設置consumes這個東東。
- 解決辦法找到了，那consumes在哪里設置呢？
答案就是在@ApiOperation這個注解里面進行設置，將consumes修改為“application/x-www-form-urlencoded”即可，例如：
@ApiOperation(value="接口說明(測試)",httpMethod="GET",consumes="application/x-www-form-urlencoded",notes="在沒有會話、沒有簽名的情況下，進入方法體")
- 那在什么情況下，參數的Content Type才是application/json呢？
當你的參數加了@RequestBody注解的時候，表示此參數接收的是json數據，這個時候你就可以將consumes寫為application/json了
3、想要知道ApiOperation注解中httpMethod等參數都能寫哪些值？
這個看api文檔吧，提供一個地址給大家：http://docs.swagger.io/swagger-core/apidocs/com/wordnik/swagger/annotations/ApiOperation.html