上一篇博客地址：springboot 1.5.4 整合rabbitMQ（十七）
1 Spring Boot集成Swagger2构建RESTful API文档
1.1 Swagger2简介
Swagger2官网：http://swagger.io/
由于Spring Boot能够快速开发、便捷部署等特性，相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。
这样一来，我们的RESTful API就有可能要面对多个开发人员或多个开发团队：IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：
由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。
随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。
为了解决上面这样的问题，本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示：
最常用的Swagger2的7个注解：
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiImplicitParam：单个参数描述
@ApiImplicitParams：用对象来接收参数
@ApiParam：单个参数描述（没有dataType属性）
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
其它若干：
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
implicit：毫无疑问的；内含的；绝对的
1.2 Spring Boot使用Swagger2
1， pom.xml引入依赖
demo项目：spring-boot-jsp，源码链接：
码云地址：https://git.oschina.net/wyait/springboot1.5.4.git
github地址：https://github.com/wyait/spring-boot-1.5.4.git
pom中引入springfox Swagger2和springfox-swagger-ui依赖
2，新增swagger2配置类
在Application类同级包下创建Swagger2Config配置类
/**
*
* @项目名称：spring-boot-jsp
* @类名称：Swagger2Config
* @类描述：Swagger2配置类
* @创建人：wyait
* @创建时间：2017年6月27日下午5:26:03
* @version：
*/
// 配置注解
@Configuration
// 自动配置Swagger2
@EnableSwagger2
public class Swagger2Config {
//配置Swagger2的Docket对象，交给Spring容器
@Bean
publicDocket createRestApi() {
//配置加载指定包下的注解
returnnew Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//测试API可设置不同组，ui界面看到api不一样
.groupName("test")
.genericModelSubstitutes(DeferredResult.class)
//.genericModelSubstitutes(ResponseEntity.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(true)
//.pathMapping("/")// base，最终调用接口后会和paths拼接在一起
.select()
.apis(RequestHandlerSelectors
.basePackage("com.wyait.boot.controller"))
.paths(PathSelectors.regex("/cat/.*"))//过滤的接口
//.paths(PathSelectors.any())//任何路径
.build();
}
//apiInfo：API接口相关描述
privateApiInfo apiInfo() {
/*
* ApiInfo apiInfo = new ApiInfo("Cat相关接口",//大标题 "Cat相关接口，主要用于测试.",//小标题
* "1.0",//版本"http://wyait.blog.51cto.com", "wyait",//作者
* "上海舞泡科技有限公司",//链接显示文字 "http://www.5pao.com/"//网站链接 );
*/
returnnew ApiInfoBuilder()
.title("cat相关API")
//大标题
.description("cat相关接口测试")
//详细描述
.version("1.0")
//版本
.termsOfServiceUrl("NOterms of service")
.contact("http://wyait.blog.51cto.com")
//作者
.license("Version1.0")
.licenseUrl("http://www.5pao.com")
.build();
/*
* return new ApiInfoBuilder()
* .title("Spring Boot中使用Swagger2构建RESTfulAPIs")
* .description("更多Spring Boot相关资料，百度一下")
*.termsOfServiceUrl("http://wyait.blog.51cto.com")
* .version("1.0.0").build();
*/
//return apiInfo;
}
/* 升级版：排除其他方法，比如返回页面的。也可以使用注解：@ApiIgnore
@Bean
public Docket createRestApi2() {
// 排除不返回json数据的接口（页面等之类的）
Predicate
@Override
public booleanapply(RequestHandler input) {
ClassdeclaringClass = input.declaringClass();
if (declaringClass== BasicErrorController.class)// 排除
return false;
if(declaringClass.isAnnotationPresent(RestController.class)) // 被注解的类
return true;
if(input.isAnnotatedWith(ResponseBody.class)) // 被注解的方法
return true;
return false;
}
};
return newDocket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.useDefaultResponseMessages(false)
.select()
.apis(predicate)
.build();
}
private ApiInfo apiInfos() {
return new ApiInfoBuilder()
.title("包含媒体、咨询、搜索引擎关键字、广告等类型接口的服务")//大标题
.version("1.0")//版本
.build();
}
*/
}
如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。
再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
3，在Controller层添加注解描述
在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户（调用方）并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。（implicit：毫无疑问的；内含的；绝对的）
@Controller
@RequestMapping("/cat")
public class CatController {
@Autowired
privateCatService catService;
/**
*
* @描述：查询cat数据
* @创建人：wyait
* @创建时间：2017年6月27日下午3:54:20
* @return
*/
@ApiOperation(value= "获取猫数据", notes= "根据猫名称获取猫数据")
@RequestMapping(value= "/findCat", method = RequestMethod.POST)
@ResponseBody
publicCat findUser(@RequestParam("name") String name) {
Catc = this.catService.findCat(name);
returnc;
}
/**
*
* @描述：查询cat数据
* @创建人：wyait
* @创建时间：2017年6月27日下午3:54:20
* @return
*/
@ApiOperation(value= "查询", notes= "根据name获取cat数据")
@ApiImplicitParam(name= "name", value = "猫名称", required = true, dataType = "String")
@RequestMapping(value= "/findByName", method = RequestMethod.GET)
@ResponseBody
publicCat findByName(@RequestParam("name") String name) {
System.out.println("=================请求参数name:"+name);
Catc = this.catService.findByName(name);
returnc;
}
@ApiOperation(value= "更新猫详细信息", notes = "根据url的id来指定更新对象，并根据传过来的cat信息来更新猫详细信息")
@ApiImplicitParams({
@ApiImplicitParam(name= "id", value = "猫ID", required = true, dataType = "Long"),
@ApiImplicitParam(name= "cat", value = "猫详细实体cat", required = true, dataType = "Cat")})
@RequestMapping(value= "/{id}", method = RequestMethod.PUT)
@ResponseBody
publicString putUser(@PathVariable Long id, Cat cat) {
System.out.println("=================put请求参数id:"+id);
//处理"/cats/{id}"的PUT请求，用来更新cat信息
this.catService.update(cat);
return"success";
}
@ApiOperation(value= "删除操作", notes= "根据id删除猫数据")
@ApiImplicitParam(name= "id", value = "猫Id", required = true, dataType = "Long")
@RequestMapping(value= "/{id}", method = RequestMethod.DELETE)
@ResponseBody
publicString deleteUser(@PathVariable Long id) {
System.out.println("=================delete请求参数id:"+id);
//删除cat
this.catService.delete(id);
return"success";
}
}
4，启动，测试
启动，访问:
http://127.0.0.1:8080/swagger-ui.html
就能看到前文所展示的RESTfulAPI的页面。我们可以再点开具体的API请求，以GET类型的/cat/findByName请求为例，可找到上述代码中我们配置的Notes信息以及参数cat的描述信息，如下图所示。
5，API文档访问与调试
注意：测试只有POST请求，可以Try it out，其他方法测试400错误！！！
在上图请求的页面中，我们看到user的Value是个输入框？是的，Swagger除了查看接口功能外，还提供了调试测试功能，我们可以点击上图中右侧的ModelSchema（×××区域：它指明了Cat的数据结构），此时Value中就有了Cat对象的模板，我们只需要稍适修改，点击下方“Try it out！”按钮，即可完成了一次请求调用！
1.3 补充
Swagger2默认将所有的Controller中的RequestMapping方法都会暴露，然而在实际开发中，我们并不一定需要把所有API都提现在文档中查看，这种情况下，使用注解@ApiIgnore来解决，如果应用在Controller范围上，则当前Controller中的所有方法都会被忽略，如果应用在方法上，则对应用的方法忽略暴露API。
项目源码，
码云地址：https://git.oschina.net/wyait/springboot1.5.4.git
github地址：https://github.com/wyait/spring-boot-1.5.4.git
spring boot系列文章：
spring boot 1.5.4 概述（一）
spring boot 1.5.4入门和原理（二）
spring boot 1.5.4 之web开发（三）
spring boot 1.5.4 整合JSP（四）
spring boot 1.5.4 集成devTools（五）
spring boot 1.5.4 集成JdbcTemplate（六）
spring boot 1.5.4 集成spring-Data-JPA（七）
spring boot 1.5.4 配置文件详解（八）
spring boot 1.5.4 统一异常处理（九）
spring boot 1.5.4 定时任务和异步调用（十）
spring boot 1.5.4 整合log4j2（十一）
spring boot 1.5.4 整合 mybatis（十二）
spring boot 1.5.4 整合 druid（十三）
spring boot 1.5.4 之监控Actuator（十四）
spring boot 1.5.4 整合webService（十五）
spring boot 1.5.4 整合redis、拦截器、过滤器、监听器、静态资源配置（十六）
spring boot 1.5.4 整合rabbitMQ（十七）
spring boot 1.5.4 集成Swagger2构建Restful API（十八）
spring boot 1.5.9 整合redis（十九）