springdoc-openapi 在沒有服務器的情況下生成 openapi yaml

Question

我有一個 Spring 引導 Gradle 項目，我想獲取它的 OpenAPI 規范 YAML 文件。

據我了解，官方swagger-core不支持 Spring 啟動項目，因此我找到springdoc-openapi ( https://github.com/springdoc/springdoc-openapi-gradle-plugin )。

似乎為了獲取 YAML/JSON 文件，在運行generateOpenApiDocs任務時， springdoc庫設置了一個帶有一些端點（/v3/api-docs）的服務器來下載文件。

1. 我使用的是默認配置，但出於某種原因，我不斷收到以下錯誤：

任務“generateOpenApiDocs”執行失敗。 無法連接到 http://localhost:8080/v3/api-docs 等待了 30 秒

似乎由於某種原因它沒有設置服務器。 我該如何解決？

2. 是否可以跳過服務器部分？ 我可以將 springdoc 配置為在構建時簡單地生成文件嗎？

Answer 1

如果您使用 spring-boot 部署 REST API，則您依賴於 servlet 容器。

OpenAPI 規范所需的元數據僅在運行時由 spring 框架提供，這解釋了運行時生成的選擇。

您可以在集成測試期間定義任何嵌入式 servlet 容器以生成 OpenAPI 規范。

Answer 2

這就是我解決問題的方式

• 指定路徑
• 在您的屬性文件中輸入：

springdoc:
  api-docs:
    path: /{your path}

• 配置插件
• 在您的 build.gradle 文件中輸入：

openApi {
    apiDocsUrl.set("http://localhost:{your port}/your path)
    
}

Answer 3

發生這種情況是因為有時嵌入式服務器需要一些時間才能啟動，並且默認設置為 30 秒。 請在您的 openAPI 塊中添加以下屬性，它會為您正常工作。 請參閱以下示例：

openApi {
apiDocsUrl.set("http://localhost:9090/v3/api-docs.yaml")
outputDir.set(file("Your Directory path"))
outputFileName.set("openapi.yaml")
forkProperties.set("-Dserver.port=9090")
waitTimeInSeconds.set(60)
} 

Answer 4

您需要在下面添加依賴項，更新版本可能存在，具體取決於您何時看到它 - intellij 會告訴您並幫助升級：

implementation('org.springdoc:springdoc-openapi-ui:1.6.11')

然后將以下行添加到您的application.properties文件中：

springdoc.api-docs.path=/api-docs

或許也去掉插件，只要有上面的依賴就沒必要了。 我擺脫了我的，一切正常。

解決依賴關系后，使用 intellij 運行按鈕或命令行正常運行應用程序。

在應用程序運行時，訪問 http://localhost:8080/swagger-ui/index.html - 假設您的應用程序在端口 8080 上運行。如果不是，請相應地使用正確的端口。

另外，您可以查看https://github.com/springdoc/springdoc-openapi-gradle-plugin/issues/10和https://github.com/springdoc/springdoc-openapi-gradle-plugin/issues/10# issuecomment-594010078 - 當我遇到同樣的問題時，它們很有幫助，向我展示了部分操作。