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分享真实的实战开发经验,一起沟通学习

  • 发表于:
  • 原文链接https://kuaibao.qq.com/s/20180609G1F2MG00?refer=cp_1026
  • 腾讯「云+社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。
  • 如有侵权,请联系 yunjia_community@tencent.com 删除。

同媒体快讯

扫码关注云+社区

领取腾讯云代金券