spring boot 1.5.4 集成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。
本文转自 wyait 51CTO博客，原文链接：http://blog.51cto.com/wyait/1978657，如需转载请自行联系原作者