springdoc-openapi 在没有服务器的情况下生成 openapi yaml

Posted 2023-03-10

【中文标题】springdoc-openapi 在没有服务器的情况下生成 openapi yaml

【英文标题】：springdoc-openapi generate openapi yaml on build without server

【发布时间】：2020-10-18 07:59:57

【问题描述】：

我有一个 Spring Boot Gradle 项目，我想获取它的 OpenAPI 规范 YAML 文件。

据我了解官方swagger-core不支持Spring boot项目，因此我找到了springdoc-openapi（https://github.com/springdoc/springdoc-openapi-gradle-plugin）。

似乎为了获取 YAML/JSON 文件，在运行 generateOpenApiDocs 任务时，springdoc 库设置了一个带有一些端点 (/v3/api-docs) 的服务器来下载文件。

我使用的是默认配置，但由于某种原因，我不断收到以下错误：

任务“generateOpenApiDocs”执行失败。 无法连接 http://localhost:8080/v3/api-docs 等了 30 秒

似乎由于某种原因它没有设置服务器。我该如何解决？

是否可以跳过服务器部分？我可以将 springdoc 配置为在构建时简单地生成文件吗？

【参考方案1】：

发生这种情况是因为有时嵌入式服务器需要一些时间才能启动，并且默认设置为 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)
 

【参考方案2】：

这就是我解决问题的方法

指定路径

在您的属性文件中输入：

springdoc:
  api-docs:
    path: /your path

配置插件

在您的 build.gradle 文件中输入：

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

【参考方案3】：

如果您使用 spring-boot 部署 REST API，则依赖于 servlet 容器。

OpenAPI 规范所需的元数据仅在运行时由 Spring 框架提供，这解释了运行时生成的选择。

您可以在集成测试期间定义任何嵌入式 servlet 容器以生成 OpenAPI 规范。

【讨论】：

看起来很麻烦，因为您需要 yaml 才能使用 open-api gradle 插件来生成 api 存根。可惜他们然后强迫每个人都扮演自己的解决方案......