Swagger增强神器：Knife4j

视频版内容：

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 了，简直完美，所以你不来试一试吗？