关键词：
上一篇博客地址：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依赖
<!-- spring boot集成Swagger2-->
<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，新增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<RequestHandler> predicate = newPredicate<RequestHandler>() {
@Override
public booleanapply(RequestHandler input) {
Class<?>declaringClass = 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 集成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 整合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（十八）
本文出自 “架构的路上” 博客，请务必保留此出处http://wyait.blog.51cto.com/12674066/1978657
springboot1.5.4集成jdbctemplate
上一篇：springboot1.5.4集成devTools（五）SpringBoot使用JdbcTemplate访问数据库springboot整合jdbcTemplate项目源码：https://git.oschina.net/wyait/springboot1.5.4.gitSpring的JdbcTemplate是自动配置的，你可以直接使用@Autowired来注入到你自己的bean中来使用... 查看详情
springboot1.5.4集成spring-data-jpa
上一篇：springboot1.5.4集成JdbcTemplate（六）1 SpringBoot使用Spring-Data-JPA访问数据库springboot整合jdbcTemplate项目源码：https://git.oschina.net/wyait/springboot1.5.4.git1.1 Spingdat 查看详情
springboot1.5.4整合druid（十三）
上一篇：springboot1.5.4整合mybatis（十二） 1 集成druid连接池springboot集成druid项目mybatis-spring-boot源码地址：https://git.oschina.net/wyait/springboot1.5.4.git 1.1 druid简介D 查看详情
springboot1.5.4整合mybatis
上一篇：springboot1.5.4整合log4j2（十一） SpringBoot集成Mybatis更多更详细的配置参考文件：application.properties和《SpringBoot之application配置详解》（新版本新增属性缺失） 或参考官网http://projects.spring.io/spring-boot/ SpringBoot集成... 查看详情
springboot1.5.4之web开发
上一篇：springboot1.5.4入门和原理（二）springBoot之web开发更多更详细的配置参考文件：application.properties和《SpringBoot之application配置详解》（新版本新增属性缺失） 或参考官网http://projects.spring.io/spring-boot/注意：SpringBoot工程默... 查看详情
springboot1.5.4统一异常处理
上一篇：springboot1.5.4配置文件详解（八） 1 SpringBoot统一异常处理SpringBoot中实现了默认的error映射，但是在实际应用中，上面你的错误页面对用户来说并不够友好，我们通常需要去实现我们自己的异... 查看详情
springboot1.5.4整合rabbitmq（十七）
上一篇：springboot1.5.4整合redis、拦截器、过滤器、监听器、静态资源配置（十六） 关于rabbitMQ原理，请参阅博客：rabbitMQ消息队列原理 1.2.2 创建spring-boot-MQ工程spring-boot-rabbitMQ项目源码，码云地址：htt... 查看详情
springboot1.5.4配置druid1.1.0(使用druid-spring-boot-starter)
原文：https://github.com/x113773/testall/issues/11###Druid最近发布了1.1.0版本，并且提供了[druid-spring-boot-starter](https://github.com/alibaba/druid/tree/master/druid-spring-boot-starter)，方便与SpringBoot集成1.首先添加依赖```& 查看详情
springboot1.5.4定时任务和异步调用
上一篇：springboot1.5.4统一异常处理（九） 1 SpringBoot定时任务和异步调用我们在编写SpringBoot应用中经常会遇到这样的场景，比如：我需要定时地发送一些短信、邮件之类的操作，也可能会定时地检查... 查看详情
springboot1.5.4aop实例
原文：https://github.com/x113773/testall/issues/121.还是首先添加依赖（使用当前springboot的默认版本）```<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-aop</ 查看详情
springboot1.5.4整合log4j2
上一篇：springboot1.5.4定时任务和异步调用（十） SpringBoot整合log4j2springboot整合log4j2项目spring-boot-jsp源码：https://git.oschina.net/wyait/springboot1.5.4.git1.1 log4j2概要对于我们开发人员来说，日志记录往往不被重视。在生产环境中，... 查看详情
springboot1.5.4连接池和事务
原文：https://github.com/x113773/testall/issues/10默认连接池---springBoot中默认支持的连接池有Tomcat、HikariCP、DBCP、DBCP2，以下摘自[官方文档](http://docs.spring.io/spring-boot/docs/1.5.4.RELEASE/reference/htmlsingle/#boot-feature 查看详情
springboot1.5.4从入门到实践
SpringBoot四个重要核心：自动配置：针对很多Sping应用程序常见的应用功能，SpringBoot能自动提供相关配置；起步依赖：告诉SpringBoot需要什么功能，它就能引入需要的库；命令行界面：这是SpringBoot的可选特性，借此你只需写代码就... 查看详情
springboot1.5.4整合redis拦截器过滤器监听器静态资源配置（十六）
上一篇：springboot1.5.4整合webService（十五） 1 SpringBoot整合redis和缓存SpringBoot中除了对常用的关系型数据库提供了优秀的自动化支持之外，对于很多NoSQL数据库一样提供了自动化配置的支持，包括：Redi... 查看详情
springboot集成swagger2在线文档
目录SpringBoot集成Swagger2在线文档前言集成SpringBoot登录接口文档示例代码效果注解说明总结SpringBoot集成Swagger2在线文档前言不得不说，前后端分离开发的工作方式给我们带来诸多好处，让前后端攻城狮们顺畅了不少后端给前端提... 查看详情
springboot之swagger2集成
一、Swagger2简单介绍 Swagger2，它可以轻松的整合到SpringBoot中，并与SpringMVC程序配合组织出强大RESTfulAPI文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以... 查看详情
springboot入门：集成swagger2
...treetable和zTree实现树形图》，本篇主要介绍了springboot集成swagger2。关于swagger的介绍，自行谷歌。我这里有在网上购买的相关视频资料，有需要可以呼叫我。1.引入相关依赖1<dependency>2<groupId>io.springfox</groupId>3&l 查看详情
springboot集成swagger2生成api接口文档(代码片段)
SpringBoot2.3.0集成Swagger2引入Swagger2相应的依赖入门示例SpringBoot2集成Swagger2后启动报错结语背景：最近在工作中发现，已经多次发现后台开发人员提供的接口协议和实际的业务代码不统一。这些现象往往都是因为开发人员在... 查看详情