上一篇博客地址：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依赖

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

</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。