Knife4jAndSpringDoc

发表于 更新于 分类于 本文字数： 2.4k 阅读时长 ≈ 2 分钟

做后端项目时，接口文档这件事基本绕不开。自己手写文档当然可以，但接口一多、参数一变、返回结构一改，文档和代码就很容易对不上。

所以很多 Spring Boot 项目最后都会引入像 SpringDoc 和 Knife4j 这样的工具。前者更偏 OpenAPI 文档生成，后者更偏文档展示和增强。它们经常一起出现，但职责其实并不完全一样。

为什么会用到这类工具

接口文档最麻烦的地方不在于写一份出来，而在于后面一直维护。

比如下面这些情况都很常见：

  • Controller 改了参数，但文档没改
  • 返回结构已经调整了，接口平台上还是旧版本
  • 不同开发人员写文档的习惯不一样，最后格式很乱

所以更稳妥的做法通常不是“手工同步文档”，而是让文档尽量从代码里自动生成出来。

这也是 SpringDoc 这类工具的价值。Knife4j 则是在这个基础上，把文档展示、调试体验和聚合能力往前推了一步。

SpringDoc 是什么

按照 springdoc-openapi 官方文档的说法，它是一个帮助 Spring Boot 项目自动生成 OpenAPI 3 文档的库。

说得简单一点，SpringDoc 做的事情就是扫描 Spring 应用里的接口、参数、返回值和相关注解，然后生成 OpenAPI 文档。生成出来的内容通常可以用 JSON、YAML 或者 UI 页面来查看。

在 Spring Boot 3 项目里，SpringDoc 现在基本已经成了比较常见的一种方案。

最常见的接入方式是加上 starter：

1
2
3
4
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

启动之后，一般就能通过下面这些地址看到文档：

  • /v3/api-docs
  • /v3/api-docs.yaml
  • /swagger-ui.html

也就是说，SpringDoc 更像是“文档生成层”。

Knife4j 是什么

按照 Knife4j 官方文档的说法，它是一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案。

如果说得更直接一点，可以把它理解成一套建立在 Swagger / OpenAPI 生态之上的增强型文档工具。它不只是把接口文档展示出来，还会在文档页面、分组、调试、聚合这类体验上继续往前做。

Knife4j 最常见的印象就是它的文档 UI 和 doc.html 页面。

所以从职责上看：

  • SpringDoc 更偏文档规范生成
  • Knife4j 更偏文档展示和增强体验

两者是什么关系

在 OpenAPI 3 这条线里，Knife4j 通常是建立在 SpringDoc 之上的。

可以简单理解成下面这个关系：

flowchart LR
    A[Spring Controller / Annotation] --> B[SpringDoc]
    B --> C[OpenAPI Document]
    C --> D[Swagger UI / Knife4j UI / Other Tools]

也就是说，SpringDoc 先负责把接口描述生成出来，Knife4j 再在这个基础上提供更强一点的展示和交互能力。

从这个角度看，它们并不是完全替代关系，而更像上下游关系。

在项目里一般怎么用

如果只是想把接口文档先跑起来，很多时候直接上 SpringDoc 就够了。

比如：

  • 项目只需要标准 OpenAPI 输出
  • 只需要基础 Swagger UI
  • 后面打算把文档导入 Apifox、Postman 或其他平台

这种情况下，SpringDoc 本身就已经很够用了。

如果你还想要更丰富一点的文档页面、更方便的调试体验，或者有聚合多个服务文档的需求，那再考虑 Knife4j 会更合适。

实际使用时要注意什么

版本兼容

这类工具和 Spring Boot、Spring Framework 版本绑定得比较紧，所以升级框架版本时，最好先确认对应的 SpringDoc 和 Knife4j 版本是否匹配。

我自己在升级 Spring 版本时，就遇到过依赖兼容问题。最后的处理方式是先保留 SpringDoc 作为 OpenAPI 生成层，再用其他工具去消费它生成出来的文档。

不要把“能生成文档”和“文档写得好”混为一谈

SpringDoc 能帮你生成接口定义，但接口描述、分组、示例、鉴权说明这些内容，还是需要你自己补。

自动生成解决的是“文档和代码同步”的问题，不是“文档一定写得清楚”的问题。

可以把 OpenAPI 结果继续交给别的工具

如果团队已经在用 Apifox、Postman 或其他接口平台，那也不一定非要把所有体验都放在 Knife4j 页面里。

一种很常见的做法就是：

  • 后端用 SpringDoc 生成标准 OpenAPI 文档
  • 其他平台把这份文档拿过去继续调试、管理和协作

也就是说，SpringDoc 负责产出标准描述，前端展示层可以有多种选择。

小结

SpringDoc 和 Knife4j 经常一起出现，但它们做的事情并不完全一样。

SpringDoc 更偏 OpenAPI 文档生成，是接口描述的基础层；Knife4j 更偏展示和增强，适合在现有文档之上提供更好的阅读和调试体验。

如果项目目标只是把 OpenAPI 文档稳定产出，那 SpringDoc 往往就够了；如果还希望文档页面更丰富、交互更强，再考虑 Knife4j 会更合适。

参考资料