springdoc openapi

重要提示： springdoc-openapi v1.8.0是支援 Spring Boot 2.x 和 1.x 的最新開源版本。

對springdoc-openapi v1專案的擴充支援現在可供需要 2023 年之後支援的組織使用。

如欲了解更多詳情，請隨時聯絡：[email protected]

springdoc-openapi位於 Open Collective 上。如果您❤️這個計畫請考慮成為贊助商。

此計畫由以下機構贊助

目錄

• 完整文檔
• 介紹
• 入門
  • springdoc-openapi 與 spring-boot 和 swagger-ui 整合的函式庫
  • 使用 OpenAPI 演示應用程式進行 Spring 啟動。
    • 演示應用程式的原始程式碼。
    • 示範 Spring Boot 2 Web MVC 與 OpenAPI 3。
    • 使用 OpenAPI 3 示範 Spring Boot 2 WebFlux。
    • 示範 Spring Boot 2 WebFlux 與功能端點 OpenAPI 3。
    • 使用 OpenAPI 3 演示 Spring Boot 2 和 Spring Hateoas。
  • 在沒有 swagger-ui 的情況下將該庫整合到 Spring Boot 3.x 專案中：
  • 使用 @ControllerAdvice 進行 REST 錯誤處理
  • 新增API資訊和安全文檔
  • spring-webflux 支援附註解的控制器
• 致謝
  • 貢獻者
  • 額外支持

完整文檔

介紹

springdoc-openapi Java 程式庫有助於使用 Spring Boot 專案自動產生 API 文件。 springdoc-openapi 的工作原理是在運行時檢查應用程序，根據 Spring 配置、類別結構和各種註釋推斷 API 語義。

此程式庫會自動產生 JSON/YAML 和 HTML 格式頁面的文件。產生的文檔可以使用swagger-api註解進行補充。

該庫支援：

• 開放API 3
• Spring-boot v3（Java 17 和 Jakarta EE 9）
• JSR-303，專用於@NotNull、@Min、@Max 和@Size。
• Swagger-ui
• OAuth 2
• GraalVM 原生鏡像

以下影片介紹了圖書館：

• https://youtu.be/utRxyPfFlDw

對於spring-boot v3支持，請確保使用 springdoc-openapi v2

這是一個基於社區的項目，並非由 Spring 框架貢獻者 (Pivotal) 維護

入門

springdoc-openapi 與 spring-boot 和 swagger-ui 整合的函式庫

• 自動將 swagger-ui 部署到 Spring Boot 3.x 應用程式
• 文件將以 HTML 格式提供，使用官方 swagger-ui jar。
• 然後，Swagger UI 頁面應位於 http://server: port/context-path/swagger-ui.html，並且 OpenAPI 描述將位於以下 json 格式的 url：http://server:port/context -路徑/v3/ api-文檔
  • server : 伺服器名稱或IP
  • port ：伺服器連接埠
  • context-path ：應用程式的上下文路徑
• 文件也可以以 yaml 格式提供，路徑如下： /v3/api-docs.yaml
• 將springdoc-openapi-ui庫新增至專案依賴項清單（無需額外配置）：

梅文

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

搖籃

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• 此步驟是可選的：對於 HTML 格式的 swagger 文件的自訂路徑，請在 spring-boot 設定檔中新增自訂 springdoc 屬性：

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

使用 OpenAPI 演示應用程式進行 Spring 啟動。

演示應用程式的原始程式碼。

使用 OpenAPI 3 示範 Spring Boot 3 Web MVC。

使用 OpenAPI 3 示範 Spring Boot 3 WebFlux。

示範 Spring Boot 3 WebFlux 和功能端點 OpenAPI 3。

示範 Spring Boot 3 和 Spring Cloud Function Web MVC。

示範 Spring Boot 3 和 Spring Cloud Function WebFlux。

示範 Spring Boot 3 和 Spring Cloud Gateway。

在沒有 swagger-ui 的情況下將該庫整合到 Spring Boot 3.x 專案中：

• 文件將在以下 json 格式的 URL 中提供：http://server:port/context-path/v3/api-docs
  • server : 伺服器名稱或IP
  • port ：伺服器連接埠
  • context-path ：應用程式的上下文路徑
• 文件也將以 yaml 格式提供，路徑如下： /v3/api-docs.yaml
• 將庫新增至項目依賴項清單。 （無需額外配置）

梅文

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-api</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

搖籃

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• 此步驟是可選的：對於 Json 格式的 OpenAPI 文件的自訂路徑，請在 spring-boot 設定檔中新增自訂 springdoc 屬性：

 # /api-docs endpoint custom path
springdoc.api-docs.path =/api-docs

• 此步驟是可選的：如果要停用springdoc-openapi端點，請在spring-boot設定檔中新增自訂 springdoc 屬性：

 # disable api-docs
springdoc.api-docs.enabled =false

使用 @ControllerAdvice 進行 REST 錯誤處理

若要自動產生文檔，請確保所有方法都使用註解聲明 HTTP 程式碼回應：@ResponseStatus。

新增API資訊和安全文檔

該庫使用 spring-boot 應用程式自動配置套件來掃描 spring bean 中的以下註釋：OpenAPIDefinition 和 Info。這些註釋聲明 API 資訊：標題、版本、許可證、安全性、伺服器、標籤、安全性和外部文件。為了獲得更好的文件產生效能，請在 Spring 託管 bean 中聲明@OpenAPIDefinition和@SecurityScheme註釋。

spring-webflux 支援附註解的控制器

• 文件也可以以 yaml 格式提供，路徑如下：/v3/api-docs.yaml
• 將庫新增至項目依賴項清單（無需額外配置）

梅文

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webflux-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

搖籃

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• 此步驟是可選的：對於 HTML 格式的 swagger 文件的自訂路徑，請在 spring-boot 設定檔中新增自訂 springdoc 屬性：

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

springdoc-openapi庫託管在 Maven 中央儲存庫上。可以在以下位置查看和存取這些工件：

發布：

• https://s01.oss.sonatype.org/content/groups/public/org/springdoc/。

快照：

• https://s01.oss.sonatype.org/content/repositories/snapshots/org/springdoc/。

致謝

貢獻者

由於貢獻者的寶貴貢獻，springdoc-openapi 具有相關性並定期更新。

感謝大家的支持！

額外支持

• Spring 團隊 - 感謝他們的支持，分享有關 Spring 專案的所有相關資源。
• JetBrains - 非常感謝您支持 springdoc-openapi 專案。