Swagger增强神器:Knife4j!用它轻松实现接口搜索、Word下载、接口过滤...
视频版内容:
Swagger 是开发中最常用的框架之一了,但 Swagger 本身又有很多不完善的地方,比如,在众多的接口中查询某一个接口,又或者是把所有的接口导出成 Word 格式等,都无法在 Swagger 中实现。
有人可能会问:为什么要把接口导成 Word 格式?这种场景还挺常见的,比如需要将接口对外部公司开放时,又或者是开发环境的网络不能对外部开放(如专线,很多医院都拉的是专线),而生产环境的 Swagger 又是关闭状态的时候,这时候只能依赖离线文档来实现接口的调用了,而离线文档最常用的格式便是 Word 了。
那么为了解决 Swagger 的这些问题,我们需要使用一个 Swagger 的增强工具来实现,而这个扩展工具就是我们今天要重点介绍的 Knife4j,那 Knife4j 长得是什么样呢?我们一起来看,如下图所示:
从这个主页可以看出,Knife4j 会将 Swagger 中设置的摘要信息(Docket)显示在欢迎页,Docket 的设置可以看我之前的文章,并且 Knife4j 还很贴心的提供了一个统计所有接口的功能,在欢迎页的最下方我们可以很清楚的看到当前 POST 接口的数量,以及 GET 的接口的数量。
PS:Knife4j 支持中文和英文两种语言展示,对于国内的小伙伴来说,可读性非常的高(因为都是中文的嘛)。
Knife4j 功能介绍
1.搜索功能
我觉得 Knife4j 最实用的一个功能就是“接口搜索”了,通过这个功能我们可以非常方便的找到我们需要的接口,如下图所示:
2.离线文档下载
Knife4j 提供了 4 种格式的离线文档下载:Markdown、Html、Word、OpenAPI 等方式,如下图所示:
3.接口过滤
可以通过 Knife4j 过滤某一类型的接口,比如过滤 GET 或者 POST 接口,如下图所示:
4.全局参数设置
如果有公共的请求参数,我们可以通过 Knife4j 轻松搞定,如下图所示:
5.更友好的接口调试
使用 Knife4j 可以更友好的实现接口调试,因为在使用 Knife4j 时,它会将必传的参数以红色边框的方式显示,这样我们就直观的区分开必填参数和非必填参数了,如下图所示:
Knife4j 使用配置
从上面的内容可以看出 knife4j 的功能是很强大的,但令我更惊喜的是它的配置异常的简单,我们只需在已经成功配置了 Swagger 的项目中(Swagger 配置可参考我的上一篇文章),添加 Knife4j 的依赖即可,配置信息如下:
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
经过以上简单的依赖添加之后,无需配置任何内容,我们就可以成功的使用 Knife4j 了。
访问 Knife4j
我们可以通过 http://localhost:8080/doc.html 访问 Knife4j 的主页,如下图所示:
总结
Swagger 作为非常欢迎的框架同时也存在着一些功能“缺陷”,那么为了弥补 Swagger 的不足,我们引入了 Knife4j 框架,使用 Knife4j 我们可以很方便的实现:接口搜索、离线文档下载、全局参数设置、接口过滤和更加友好的接口测试等功能。然而和它的功能同样令人惊讶的是它的配置,在使用 Knife4j 时,我们只需要在项目中添加它的引用,之后无需任何多余的操作就可以直接使用 Knife4j 了,简直完美,所以你不来试一试吗?