一、前言
讓我們先理一下springfox與swagger的關系。
swagger是一個流行的API開發框架，這個框架以“開放API聲明”（OpenAPI Specification，OAS）為基礎，對整個API的開發周期都提供了相應的解決方案，是一個非常龐大的項目（包括設計、編碼和測試，幾乎支持所有語言）。
OAS本身是一個API規范，它用於描述一整套API接口，包括一個接口是GET還是POST請求啊，有哪些參數哪些header啊，都會被包括在這個文件中。它在設計的時候通常是YAML格式，這種格式書寫起來比較方便，而在網絡中傳輸時又會以json形式居多，因為json的通用性比較強。
由於Spring的流行，Marty Pitt編寫了一個基於Spring的組件swagger-springmvc，用於將swagger集成到springmvc中來。而springfox則是從這個組件發展而來，同時springfox也是一個新的項目，本文仍然是使用其中的一個組件springfox-swagger2。
pringfox-swagger2依然是依賴OSA規范文檔，也就是一個描述API的json文件，而這個組件的功能就是幫助我們自動生成這個json文件，我們會用到的另外一個組件springfox-swagger-ui就是將這個json文件解析出來，用一種更友好的方式呈現出來。
這是入門，我們簡單地介紹springfox-swagger2的配置，幫助各位順利地實現使用，文中有很多自己的理解，若有錯誤，歡迎批評指正。
二、配置流程說明
在開始編碼之前，我們先對配置的流程有個大致的了解。
在前言中，我們知道，我們的第一個任務就是生成一個滿足OSA規范的json文件（當然，創建一個spring的項目就不說了）。對於這個任務，springfox為我們提供了一個Docket（摘要的意思）類，我們需要把它做成一個Bean注入到spring中，顯然，我們需要一個配置文件，並通過一種方式（顯然它會是一個注解）告訴程序，這是一個Swagger配置文件。
一個OSA規范文檔需要許多信息來描述這個API，springfox允許我們將信息組合成一個ApiInfo的類，作為構造參數傳給Docket（當然也可以不構造這個類，而直接使用null，但是你的這個API就太low了）。
接下來，我們要寫控制器了，當然這不重要，不用springfox你依然要寫控制器，重要的是要告訴springfox，這個控制器是一個需要他來收集API信息的控制器，不用說，這依然會采用注解的方式，同時，我們為了將配置文件與控制器結合起來，需要在配置文件中指明在什么位置收集可能是API的控制器的信息。
到這里，生成OSA規范的json文件的配置就結束了。雖然生成過程比我敘述的更復雜，但這些程序都會幫我們完成，我們可以通過類似http://localhost:8080/demo/v2/api-docs的路徑來查看這個json文件。這個v2/api-docs就是springfox默認的生成文檔的路徑。
接下來，我們需要將它可視化顯示出來，如果使用swagger-springmvc，我們需要單獨去下載一個swagger ui的顯示頁面包，並將其中的路徑改為上面的http://localhost:8080/demo/v2/api-docs，這里你就可以感受到，swagger ui就是在解析一個json文件了。你依然可以這么做，不過springfox專門提供了一個springfox-swagger-ui組件，不需要配置，我們只需要引入這個依賴的組件就可以看到最終的效果了，而這個路由會是http://localhost:8080/demo/swagger-ui.html。
三、引入依賴
如果我寫的不錯，相信看到這里，你就大致了解了springfox swagger2的使用流程了。那么，我們進入正式編碼的第一步：引入依賴。
這里我們使用maven引入依賴，大家可以到http://mvnrepository.com上搜索springfox，便可以看到Springfox Swagger2和Springfox Swagger Ui，然后就可以從中獲取最新的資源了。如下：
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
此外還需要一個依賴組件：
<dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.6.6</version> </dependency>
四、一個簡單的配置文件
為了清晰，我們可以先在常用的源碼包里建一個config目錄，並在里面創建一個SwaggerConfig.java文件，這是一個spring的配置文件，所以位置和文件名都影響不大。
先上代碼（這里參考了博客http://blog.csdn.net/u012476983/article/details/54090423）：
@Configuration //必須存在 @EnableSwagger2 //必須存在 @EnableWebMvc //必須存在 @ComponentScan(basePackages = {"com.xiaoming.SpringMVC.controller"}) //必須存在 掃描的API Controller package name 也可以直接掃描class (basePackageClasses) public class SwaggerConfig{ @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()); } private ApiInfo apiInfo() { Contact contact = new Contact("小明", "http://www.cnblogs.com/getupmorning/", "zhaoming0018@126.com"); return new ApiInfoBuilder() .title("前台API接口") .description("前台API接口") .contact(contact) .version("1.1.0") .build(); } }
由於各位肯定用的是IDE，這里就不寫各種import了。
首先，這個SwaggerConfig類有四個注解，看名稱就可以明白是什么意思。其中，@Configuration，@EnableWebMvc和@ComponentScan是Spring的注解，而@EnableSwagger2則是用來啟動Swagger支持，表示這是一個Spring Swagger的配置文件。
之后，定義了一個Bean方法CustomDocket，Spring中名字並不重要，重要的是它返回一個Docket類，DocumentationType.SWAGGER_2作為Docket構造方法的參數，指定了所用的swagger版本2.0，官網上已經在預告3.0版本了。而之后的apiInfo則是調用接下來的apiInfo函數，來創建Docket的信息。apiInfo函數采用ApiInfoBuilder來創建ApiInfo類。
五、一個控制器
其實，控制器不需要配置，就已經會被springfox swagger識別了，不過我們這里象征性地加上一個描述信息：
@Controller
@RequestMapping("/test") public class TestController { @ApiOperation(value="一個測試API",notes = "第一個測試api") @ResponseBody @RequestMapping(value = "/hello",method = RequestMethod.GET) public String hello() { return "hello"; } }
這里僅僅多了一個@ApiOperation注解，別的和一個普通的springmvc的控制器完全一致。
實際上，為了形成一個完整的api文檔，需要添加的注解常常很多，若是都寫在同一個文件里就會顯得臃腫，我們常常會寫一個接口文件，將注解都放在接口文件中，然后再用一個實體類來實現控制器，算是實現配置和邏輯分離了吧。
六、查看接口文件和文檔
若是沒有問題，現在可以部署項目，並打開http://localhost:8080/demo/v2/api-docs：
Firefox提供了查看JSON的插件，推薦大家搜索試試看。
廢話不多說，這里可以看到之前配置的諸多信息。注入description，version，title等。並且確實有TestController的信息。
最后，我們打開http://localhost:8080/swagger-ui.html，便可以看到一個漂亮的界面了：
