SpringBoot项目实战：整合Swagger2构建强大的Restful Api接口文档（一）

微服务方向：springboot, springCloud, Dubbo

分布式/高并发： 分布式锁， 消息队列RabbitMQ

大数据处理： Hadoop, spark, HBase等

python方向： python web开发

一，前言

这两天有新项目即将开工，目前采用前后端分离的模式开发，我也是第一次进行这样的模式，但是公司有没有很有经验的大佬指点， 之前就靠自己在网上查阅大量的资料，搭建起了springboot+Dubbo+zookeeper的基本框架， 并采用了Maven的多模块开发，也是踩过很多的坑，不过沉淀下来的确是满满的经验和教训。目前这一套基础框架也已经使用到生产环境当中。现在的项目也是基于maven的多模块开发， 一步一步的搭建起满足项目需求的脚手架， 方便以后可以更快速的开发新的项目。

前后端分离， 就是后端只负责提供前端的接口，为了减少与前端的沟通成本， 可以更直观，快速地与前端人员进行接口对接， 就少不了接口文档， 而目前最流行地接口文档插件就是swagger， 目前使用Swagger2版本。

我这两天就在负责搭建Swagger2， 即便网上有很多这方面的教程， 但是都比较零散， 使得我在搭建过程中， 总是会出现很多莫名奇妙的问题， 出现这些问题的地方， 也没有一篇好的总结。所以我把自己在项目中遇到的情况及解决方案记录下来， 如果我们遇到同样的情况， 也方便查阅。

二， 开始

1.引入Swagger依赖

在pom.xml中引入 和

io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0

2. 创建Swagger2配置类

参考网上的配置，根据实际项目修改一下就可以了。

package cn.rayson.config;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** * * Swagger2配置类 * @author 方雷(Rayson) * @微信公众号: rayson_666(Rayson开发分享) * 分享springBoot springCloud技术, 以及python,大数据学习系列 * @个人博客: http://blog.chargingbunk.cn/ * @简书: https://www.jianshu.com/u/5b0de5c8dc56 * 2018年6月9日 */@Configuration@EnableSwagger2public class Swagger2Config { //swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等 @Bean public Docket defaultApi(){ return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("默认分组").select() .apis(RequestHandlerSelectors.basePackage("cn.rayson.controller")).paths(PathSelectors.any()).build(); } //构建 api文档的详细信息函数,注意这里的注解引用的是哪个 // 预览地址:swagger-ui.html private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("利用swagger构建测试系统api文档") .description("接口访问地址：http://localhost:8080/, by 方雷") .termsOfServiceUrl("http://localhost:8080/") //.contact("方雷") .version("1.0") .build(); }}

如上代码所示， 通过@Configuration注解， 让springboot来加载该类的配置。在通过@EnableSwagger2注解来启用Swagger2。

再通过@Bean注入Docket实体类， apiInfo()用来创建该api的基本信息，这些信息将会展现在文档页面中。

select() 函数会返回一个ApiSelectorBuilder实例，用来控制哪些接口暴露到swagger页面中。 本例采用指定包路径来定义， Swagger会扫描该包下的所有Controller定义的api, 并生成文档展现在swagger页面中（除了接口被@ApiIgnore指定的会被忽略）

3. 编写Controller并进行Restful接口文档测试

在Swagger2配置的包扫描路径下， 新建一个Controller

package cn.rayson.controller;import java.util.HashMap;import java.util.Map;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.ResponseBody;import org.springframework.web.bind.annotation.RestController;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiOperation;@Api(value="测试api", tags="测试api")@RestControllerpublic class RestTestController { @ApiOperation(value="获取信息", notes="根据url的id来获取信息") @ApiImplicitParam(name = "id", value = "用户ID", required = true) @RequestMapping("/test") @ResponseBody public Object index(Integer id){ Map map = new HashMap(); map.put("name", "test"); map.put("age", 13); return map; } }

具体注解什么意思，可以自行百度，我们的目的是能成功访问到swagger页面，至于以后再慢慢了解。

4. 运行成功后的Swagger效果

5. 最后来看看Swagger2的常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数

三，总结

以上就是SpringBoot整合Swagger2的整体过程，也是我们百度搜索出现基本上已经算是烂大街，随便一搜就可以找到。我为什么又要写呢？当然是保证整个知识的完整性， 为接下来要分享的踩坑并填坑做铺垫，为以后的项目开发中少走弯路。

添加关注，Rayson分享真实的实战开发经验，一起沟通学习