Swagger 最初作為一套規範而問世，後來在 2015 年捐贈給Linux基金會後演變為 OpenAPI 規範（OAS）。這次轉變標誌着 API 文檔編寫和互操作性的一次進步，使其向 OpenAPI 3.0 過渡。在現今的行業討論中，提到 Swagger 通常指的是 SmartBear Software 開發的一套用於實現 OpenAPI 規範的工具。這套工具包括開源、免費和商業工具的組合，支持 API 生命週期的各個開發階段。
使用 Swagger 工具的核心在於採用設計優先的原則，把生成 API 文檔視為開發過程的基石。開發者可以根據自己的偏好選擇方法：一些人偏好使用 Swagger Editor 在線創建 API 文檔，而另一些人則偏好編寫代碼時註釋，讓文檔自動生成。這兩種方法都為簡化和優化開發過程提供了路徑。
其中，Spring Boot 項目的集成已表現出良好的適應性，Springfox和Springdoc作為領先的開源庫促進了這一整合。
Springfox與Springdoc深入探討
Springfox：借鑑傳統
Springfox 作為 Swagger 的 Java 實現，幫助生成兼容 Swagger 2.0 規範的 API 文檔。它通過一系列註解為開發者提供了生成相應 API 文檔的能力。此外，Springfox 還提供了可擴展接口，允許定製文檔生成過程以滿足特殊需求。儘管它因支持 Swagger 2 規範而被廣泛使用，但更新速度緩慢和與新版本 Spring Boot 的兼容問題一直是人們關心的問題。
Springdoc：新興前沿
與此同時，Springdoc 因其與 Spring Boot 的深度集成以及支持 OpenAPI 3.0 規範而脱穎而出。它涵蓋了更廣泛的Spring項目，包括 Spring WebMvc、Spring WebFlux、Spring Data Rest 和 Spring Security。以快速更新和生成 OpenAPI 3.0 規範文檔而聞名，Springdoc 也為用户提供了自定義文檔生成過程的能力，儘管目前支持的插件較少。
使用Springdoc-openapi發展文檔
springdoc-openapi Java 庫為 Spring Boot 應用中自動化生成 API 文檔提供了創新解決方案。它通過審查應用的 Spring 配置、類結構和註釋來推斷 API 語義，產生格式化的 JSON/YAML 和 HTML 文檔。
快速開始 Springdoc
- 安裝依賴: 確認在項目的 POM 文件中加入最新版的
springdoc-openapi-ui依賴。 - 啓用Swagger: 在
application.yml文件中修改配置以根據需要啓用或禁用 Swagger 3。 - 配置SwaggerController: 實現一個
Swagger3Config類來配置 API 分組，併為操作添加自定義參數或頭部。 - 註釋實體類: 對你的實體類使用 Swagger 的
@Schema註釋，以便準確地進行文檔編寫。 - 控制器註釋: 通過為控制器方法添加 Swagger 的
@Operation和@Parameter註釋來精確定義 API。
訪問 Swagger UI
通過訪問http://server:port/context-path/swagger-ui.html來查看生成的 Swagger 文檔。
其他方式
雖然springdoc-openapi為 API 文檔提供了無與倫比的支持，但將其與 Apifox 整合為分享和同步 API 細節提供了一個吸引人的途徑。Apifox 提供了一個全面的平台，支持 API 設計、文檔、測試和協作功能，能夠自動解析代碼註釋並從 Javadoc、KDoc 和 ScalaDoc 生成 API 文檔。通過使用 IntelliJ IDEA 的 Apifox Helper 插件，開發人員可以在不離開 IDE 的情況下與 Apifox 項目同步他們的文檔。此外，Apifox 通過其直觀的UI豐富了 API 管理體驗，支持從 IDEA 直接啓動內部測試和導出文檔。
對於希望提升 API 文檔和協作工作流的開發人員，採用 Apifox 與 Springdoc-openapi 可能成為改變遊戲規則的策略。
