記得剛開始想在 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 進行描述就可以。
