Swagger、Springfox、Springdoc-openapi 到底是什么关系

记得刚开始想在 SpringBoot 应用中使用 Swagger 生成 API 文档时，在 Swagger 官网上想找如何在 SpringBoot 中使用的指导，结果肯定是找不到，因为当时不清楚 Swagger 的定位是什么，只知道可以用它生成 API 文档。所以就想写这篇文章，重点总结一下 Swagger 和 Springfox、Springdoc-openapi 有什么关系及原理，还有 1 个增强的工具 Knife4j，不会描述具体用法。

OpenAPI 规范

讲 Swagger 之前，要先介绍一下 OpenAPI 规范（OpenAPI Specification，简写为 OAS）。

OpenAPI规范（前身为 Swagger 规范）是一种用于描述 REST API 的格式，可以用 YAML 或 JSON 格式编写，可以描述 API 的所有信息，包括：

• endpoint 及其操作方法，比如 GET
• 操作参数
• 认证方式
• 联系信息、许可证、使用条款及其他相关信息

Swagger

Swagger 是围绕 OpenAPI 规范构建的一组开源工具，可以用来设计、构建、记录和使用 REST API，官网是 https://swagger.io/。

Swagger 的主要工具包括：

• Swagger Editor：基于浏览器的编辑器，可用于编写 OpenAPI 定义。
• Swagger UI：将 OpenAPI 定义渲染成交互式文档。（OpenAPI 定义是 YAML 或 JSON 格式，可以是手动编写的文件，也可以是调用接口获取的数据。）
• Swagger CodeGen：通过 OpenAPI 定义生成服务端桩函数和客户端库（客户端语言支持 40 多种）。
• Swagger Core：用于创建、使用和操作 OpenAPI 定义的 Java 相关工具库。
• Swagger Parser：用于解析 OpenAPI 定义的 Java 工具库。
• Swagger APIDom：为不同描述语言和序列化格式的API提供统一的结构化描述规范。
• 除了上面的，还可以在此网址 https://swagger.io/tools/open-source/open-source-integrations/ 查看其它 Swagger 相关的工具，包括 Swagger 官方提供的工具以及其他社区开发的用于将 Swagger 集成到不同编程语言的工具。
• Swagger官网还提供了用于 API 设计和协作的线上平台 API Hub 。

综上所述，Swagger 是基于 OpenAPI 规范对 REST API 进行管理的一组工具。

• 功能上它不仅能生成 API 文档，可以设计 API、生成 API 代码、测试 API 等。
• 它是和编程语言无关的，适用于Java、Go、Python、JavaScript等多种编程语言。（所以去 Swagger 官网找如何在 SpringBoot 中使用的操作指导找不到）

Springfox & Springdoc-openapi

Springfox 和 Springdoc-openapi 既不是 Swagger 官方提供的，也不是 Spring 官方提供的，而是由两个不同的社区团队开发的，方便开发者将 Swagger 集成到 Spring 框架中。

Springfox 在 2020 年 7 月发布 3.0.0 版本后，就没有更新过了。

所以现在如果要在 SpringBoot 应用中使用 Swagger，就用 Springdoc-openapi ，官网是 https://springdoc.org/ 。

它的核心原理是通过动态解析 Spring MVC 的控制器（Controller）、方法（Handler Methods）、模型（DTOs）等元数据，结合注解（如 Swagger 注解或 JSR-303 校验注解），自动构建 OpenAPI 规范的 JSON/YAML 描述文件，最终通过 Swagger UI 或其他工具（比如 Redoc ）渲染成可视化文档。

当引用 Springdoc-openapi 的库时，它会自动引用 Swagger 相关的库，比如：swagger-annotations-jakarta-x.x.x.jar、swagger-core-jakarta-x.x.x.jar、swagger-ui-x.x.x.jar 等，其中 swagger-ui-x.x.x.jar 是将 html、css、javascript 等静态资源文件打包到 resources 目录下的，这样启动 SpringBoot 应用后，就可以通过 /swagger-ui/index.html 访问 Swagger-UI 的页面，Swagger-UI 会调用 /v3/api-docs 接口获取 springdoc-openapi 解析出来的 OpenAPI JSON 数据，再将数据展示到页面上。

Knife4j

Knife4j 是一个集Swagger2 和 OpenAPI3
为一体的增强解决方案，它是基于 Springfox 和 Springdoc-openapi 的，是由国内社区开发的，官网是 https://doc.xiaominfo.com/ 。

使用 Knife4j 后，既可以通过 /swagger-ui/index.html 访问 Swagger-UI 页面，也可以通过 /doc.html 访问 knife4j 的页面。

Knife4j 还支持将接口文档离线导出为 markdown、html、word 等格式。

总结

了解了 Swagger、Springfox、Springdoc-openapi、Knife4j 的关系后，就可以去对应的官网找文档学习具体的用法了。

如果要在 SpringBoot 中使用 Swagger 生成 API 文档，直接使用 Springdoc-openapi 或 Knife4j 即可。
如果不需要自定义内容，引入对应的库之后，直接用 Swagger 的注解对 API 进行描述就可以。