本節內容：
- 什么是Swaggger
- Springfox與Swagger的關系
- SpringMVC集成springfox-swagger2
一、什么是Swaggger
Swagger是一個流行的API開發框架，這個框架以“開放API聲明”（OpenAPI Specification，OAS）為基礎，對整個API的開發周期都提供了相應的解決方案，是一個非常龐大的項目（包括設計、編碼和測試，幾乎支持所有語言）。
二、Springfox與Swagger的關系
OSA本身是一個API規范，它用於描述一整套API接口，包括一個接口是GET還是POST請求啊，有哪些參數哪些header啊，都會被包括在這個文件中。它在設計的時候通常是YAML格式，這種格式書寫起來比較方便，而在網絡中傳輸時又會以json形式居多，因為json的通用性比較強。
由於Spring的流行，Marty Pitt編寫了一個基於Spring的組件swagger-springmvc，用於將swagger集成到springmvc中來。而springfox則是從這個組件發展而來，同時springfox也是一個新的項目，本文使用的是其中的一個組件springfox-swagger2。
如果想要集成swagger-springmvc就相對麻煩一點，因為要把它的靜態文件copy到自己的項目中。springfox-swagger2依然是依賴OSA規范文檔，也就是一個描述API的json文件，而這個組件的功能就是幫助我們自動生成這個json文件，我們會用到的另外一個組件springfox-swagger-ui就是將這個json文件解析出來，用一種更友好的方式呈現出來。
三、SpringMVC集成springfox-swagger2
1. 添加依賴的jar包
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
2. spring-mvc.xml中添加映射靜態的配置
<mvc:default-servlet-handler />
3. 配置文件
在源碼包里建一個config目錄，並在里面創建一個SwaggerConfig.java文件，這是一個spring的配置文件，所以位置和文件名都影響不大。
SwaggerConfig.java
package com.spring.learn.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Created by jkzhao on 1/19/18.
*/
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.spring.learn.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring 中使用Swagger2構建RESTful APIs")
.termsOfServiceUrl("http://www.cnblogs.com/zhaojiankai/")
.description("springmvc swagger2")
.contact(new Contact("zhaojiankai", "http://www.cnblogs.com/zhaojiankai/", "743833196@qq.com"))
.version("1.1")
.build();
}
}
這個SwaggerConfig類有四個注解，其中，@Configuration是Spring的注解，而@EnableSwagger2則是用來啟動Swagger支持，表示這是一個Spring Swagger的配置文件。
之后，定義了一個Bean方法createRestApi，Spring中名字並不重要，重要的是它返回一個Docket類，DocumentationType.SWAGGER_2作為Docket構造方法的參數，指定了所用的swagger版本2.0，官網上已經在預告3.0版本了。而之后的apiInfo則是調用接下來的apiInfo函數，來創建Docket的信息。apiInfo函數采用ApiInfoBuilder來創建ApiInfo類。
然后運行項目，在瀏覽器輸入：http://{ip}:{port}/{projectname}/swagger-ui.html
它會把按照controller，把所有的接口都加載進來。
我的目錄結構如圖：
然后，就是接口名稱和參數的說明：
常用注解：
- @Api()用於類名
- @ApiOperation()用於方法名
- @ApiParam()用於參數說明
- @ApiModel()用於實體類
- @ApiModelProperty用於實體類屬性
更詳細的說明請參見官方注解說明文檔
【示例】：
ApiController.java
@Controller
@RequestMapping("/api")
@Api(value = "api接口", description="用戶相關操作")
public class ApiController {
@Autowired
private UserService userService;
@RequestMapping(value = "/user", method = {RequestMethod.GET})
@ApiOperation(value = "用戶查詢服務", notes = "根據傳過來的user_id來查詢用戶")
public String getUserById(@ApiParam(value = "用戶id") String user_id, ModelMap map){
User user = userService.getUserById(user_id);
map.put("user", user);
return "success";
}
}
User.java
@ApiModel(value = "用戶") public class User { private String user_id; @ApiModelProperty(value = "用戶名") private String user_name; @ApiModelProperty(value = "密碼") private String password; ...
重新運行起項目，訪問效果如下：
