作者：方雷
个人博客：http://blog.chargingbunk.cn/
微信公众号：rayson_666(Rayson开发分享)
个人专研技术方向：
- 微服务方向：springboot, springCloud, Dubbo
- 分布式/高并发： 分布式锁， 消息队列RabbitMQ
- 大数据处理： Hadoop, spark, HBase等
- python方向： python web开发
喜欢的朋友们可以关注我的或微信公众号(rayson_666), 一起交流学习， 后期会不断更新有经验的干货.
一，前言
这两天有新项目即将开工，目前采用前后端分离的模式开发，我也是第一次进行这样的模式，但是公司有没有很有经验的大佬指点， 之前就靠自己在网上查阅大量的资料，搭建起了springboot+Dubbo+zookeeper的基本框架， 并采用了Maven的多模块开发，也是踩过很多的坑，不过沉淀下来的确是满满的经验和教训。目前这一套基础框架也已经使用到生产环境当中。现在的项目也是基于maven的多模块开发， 一步一步的搭建起满足项目需求的脚手架， 方便以后可以更快速的开发新的项目。
前后端分离， 就是后端只负责提供前端的接口，为了减少与前端的沟通成本， 可以更直观，快速地与前端人员进行接口对接， 就少不了接口文档， 而目前最流行地接口文档插件就是swagger， 目前使用Swagger2版本。
我这两天就在负责搭建Swagger2， 即便网上有很多这方面的教程， 但是都比较零散， 使得我在搭建过程中， 总是会出现很多莫名奇妙的问题， 出现这些问题的地方， 也没有一篇好的总结。所以我把自己在项目中遇到的情况及解决方案记录下来， 如果我们遇到同样的情况， 也方便查阅。
二， 开始
1.引入Swagger依赖
在pom.xml中引入 springfox-swagger2 和 springfox-swagger2-ui
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
@EnableSwagger2
public 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")
@RestController
public 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的整体过程，也是我们百度搜索出现基本上已经算是烂大街，随便一搜就可以找到。我为什么又要写呢？当然是保证整个知识的完整性， 为接下来要分享的踩坑并填坑做铺垫，为以后的项目开发中少走弯路。