本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API
效果图：
第一步：maven依赖加入
<!--swagger2-->
<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>第二步：Swagger2配置类添加
/**
* http://localhost:8090/swagger-ui.html
* @author zhenghuasheng
* @date 2017/11/8.11:07
*/
@Configuration
@EnableWebMvc
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("客服系统RESTful APIs")
.description("HTTP方法、参数说明，以及模拟实时调用结果展示，使用方法请自行参照Swagger2文档")
.termsOfServiceUrl("http://192.168.4.105:20400/")
.contact(new Contact("zhs","http://192.168.4.105:20400/","[email protected]"))
.version("1.0.0")
.build();
}
}第三步：spring配置文件添加Swagger2静态文件配置
<mvc:default-servlet-handler/>
<!--静态文件标示 -->
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>第四步：拦截器检查
如果项目中有拦截器配置，需要将Swagger2的静态文件访问放行
<mvc:exclude-mapping path="/swagger*/**"/>
<mvc:exclude-mapping path="/v2/**"/>
<mvc:exclude-mapping path="/webjars/**"/>第五步：添加API描述
/**
* Created by zhenghuasheng on 2017/9/11.16:34
*/
@Api(value = "AchieveController" ,description = "订单业绩查询和导出")
@Controller
@RequestMapping("/achieve")
public class AchieveController {
@Autowired
private ActivityUserFacade activityUserFacade;
private static Logger logger = LoggerFactory.getLogger(AchieveController.class);
/**
*
* @param request
* @param page
* @param pageSize
* @return
*/
@ApiOperation(value = "主动服务订单业绩列表", notes = "getOrderKpis",httpMethod = "POST")
@ResponseBody
@RequestMapping(value = "/list")
public ResultVo<JqGridPaperVo> getOrderKpis(HttpServletRequest request, @RequestParam(defaultValue = "1") Integer page, @RequestParam(defaultValue = "20") Integer pageSize) {
}第六步：启动服务，访问http://ip:port/swagger-ui.html
Swagger2文档：http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
注解说明：
@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的，比如你有好几个controller，分别属于不同的功能模块，那这里我们就可以使用tags来区分了，看上去很有条理
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数放在哪个地方
header–>请求参数的获取：@RequestHeader
query–>请求参数的获取：@RequestParam
path（用于restful接口）–>请求参数的获取：@PathVariable
body（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如”请求参数没填好”
response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）表明这是一个被swagger框架管理的model，用于class上
@ApiModelProperty 这里顾名思义，描述一个model的属性，就是标注在被标注了@ApiModel的class的属性上，这里的value是对字段的描述，example是取值例子，注意这里的example很有用，对于前后端开发工程师理解文档起到了关键的作用，因为会在api文档页面上显示出这些取值来；这个注解还有一些字段取值，可以自己研究，举例说一个：position，表明字段在model中的顺序
新版本 swagger-bootstrap-ui ：http://www.oschina.net/news/91637/swagger-bootstrap-ui-1-7
问题总结：
1，SpringMVC中使用FastJsonHttpMessageConverter时Swagger2失效的解决办法
FastJson是阿里巴巴开源的高性能JSON转换工具。我们在使用Spring MVC需要进行JSON转换时，通常会使用FastJson提供的FastJsonHttpMessageConverter。但是在我们使用了Swagger2的工程中使用它之后，我们的Api文档就无法工作了（虽然swagger-ui界面可以展现，但是没有任何api内容，并且通过访问/v2/api-docse，我们得到的返回时{}，而不是之前的文档配置内容了
更新fastjson版本
更新fastjson版本为1.2.10以上，在之前的版本中FastJsonHttpMessageConverter没有暴露fastjson对Serializer配置。可以方便我们加入对springfox.documentation.spring.web.json.Json的序列化支持。