技术派API文档之Knife4j（👍强烈推荐）

大家好，我是技术派的二哥呀。

今天由我来给大家讲一下技术派是如何整合 Knife4j 替换丑陋的 Swagger 实现 API 文档生成和 RESTful Web 测试。

一般在使用 Spring Boot 开发前后端分离项目的时候，都会用到 Swagger，但随着系统功能的不断增加，接口数量的爆炸式增长，Swagger 的使用体验就会变得越来越差，比如请求参数为 JSON 的时候没办法格式化，返回结果没办法折叠，还有就是没有提供搜索功能。

而 Knife4j 完美弥补了这些不足，赋予了 Swagger 更强的生命力和表现力。

关于 Swagger

从严格意义上来讲，Swagger 是一套完整的用于生成、描述和调用 RESTful 接口的 Web 服务。它提供了很多组件，比如说：

• Swagger Editor：一个在线编辑器，用于编写和验证 OpenAPI 规范（以前叫 Swagger 规范）的 YAML 或 JSON 文件。通过 Swagger Editor，我们可以可视化地设计和编辑 API 文档，同时还可以实时预览生成的 API 文档。
• Swagger UI：一个可视化工具，用于显示生成的 API 文档。它允许我们直接在浏览器中查看和测试 API。Swagger UI 可以自动从 OpenAPI 规范文件生成交互式的 API 文档。
• Swagger Codegen：一个代码生成器，用于生成服务器端和客户端代码。通过 Swagger Codegen，我们可以根据 OpenAPI 规范文件自动生成各种编程语言（如 Java、Python、Ruby 等）的 API 客户端代码、服务器端代码，以及 API 文档。

说得直白点就是，Swagger 可以将项目中想要暴露的接口展示在页面上，这样，我们就可以直接进行接口调用和测试，能在很大程度上提升开发的效率。

比如说，一个后端程序员写了一个登录接口，想要测试自己写的接口是否符合预期的话，就得先模拟用户登录的行为，包括正常的行为（输入正确的用户名和密码）和异常的行为（输入错误的用户名和密码），这就要命了，非常繁琐。

但有了 Swagger 后，可以通过简单的配置生成接口的展示页面，把接口的请求参数、返回结果通过可视化的形式展示出来，并且提供便捷的测试服务。

• 前端程序员可以通过接口展示页面查看需要传递的请求参数和返回的数据格式，不需要后端程序员再编写接口文档了；
• 后端程序员可以通过接口展示页面测试验证自己的接口是否符合预期，降低了开发阶段的调试成本。

前后端分离就很完美的落地了，有没有？

Swagger 官网地址看这里：https://swagger.io/

那在 Swagger 出现之前，局面就比较糟糕。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

大家都被无情地折磨，痛不堪言。。。

Swagger 定义了一套规范，你只需要按照它的规范去定义接口及接口相关的信息，然后通过 Swagger 衍生出来的一系列工具，就可以生成各种格式的接口文档，以及在线接口调试页面等等。

那只要及时更新 Swagger 的描述文件，就可以自动生成接口文档了，做到调用端代码、服务端代码以及接口文档的一致性。

但 Swagger 的界面非常丑陋，我给大家看一下没用 Knife4j 美化时的界面，简直没法看。😝

关于 Knife4j

鉴于此，我们直接上 Knife4j，Knife4j 的前身是 swagger-bootstrap-ui，是 springfox-swagger-...