如何在不启动服务的情况下在 WebFlux 项目中生成 OpenAPI 规范作为 Maven 构建的一部分

Question

我们在 WebFlux 项目中使用 SpringDoc 来注释我们的 API 并从 UI 提供 OpenAPI 文档。但是，现在我们需要作为 Maven 构建的一部分生成的 OpenAPI 文件。

SpringDoc 有一个 plugin 从运行ning 服务中获取文件，该服务已由 spring 插件启动，但我们的服务需要很多东西才能被设置为运行。我们在测试的@BeforeClass 中进行此设置，不想提取该设置（和相应的清理），以便可以将服务作为 Maven 构建的一部分启动。此外，我们计划最终停止为我们的测试启动服务，而是使用模拟，因此添加一个测试以从运行ning 测试中检索文件只是一个临时解决方案（不想维护启动代码只是为了检索 OpenAPI 文档）。

我试过使用来自 swagger-core 的 swagger-maven-plugin，但它似乎需要我们没有使用的 jaxrs。我也研究过 SpringFox，但它也没有提供所需的功能。

关于如何在不启动服务的情况下为 WebFlux 项目生成 OpenAPI 文档作为 Maven 构建的一部分的任何想法？

Answer 1

您可以尝试使用 OpenAPI 工具项目中的以下 OpenAPI Maven 插件。它提供的优势是，即使您运行您的构建没有经过测试并且只要没有编译错误，它也能正常工作。

<plugin>
    <groupId>io.openapitools.swagger</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>2.1.4</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <swaggerConfig>
            <servers>
                <server>
                    <url>https://www.example.com:8080</url>
                </server>
            </servers>
            <info>
                <title>${project.name}</title>
                <description>${project.description}</description>
                <version>{project.version}</version>
                <contact>
                    <name>Some Name</name>
                    <url>example.com</url>
                    <email>help@example.com</email>
                </contact>
            </info>
        </swaggerConfig>
        <resourcePackages>com.example.mypackages</resourcePackages>
        <useResourcePackagesChildren>true</useResourcePackagesChildren>
        <outputDirectory>${project.basedir}/generated/openapi/</outputDirectory>
        <outputFilename>openApiSpec</outputFilename>
        <outputFormats>YAML</outputFormats>
        <prettyPrint>true</prettyPrint>
        <attachSwaggerArtifact>true</attachSwaggerArtifact>
    </configuration>
</plugin>

<!-- Use the below plugin if you want to generate an HTML client (Swagger UI) using the above specification -->
<plugin>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.21</version>
    <executions>
        <execution>
            <phase>prepare-package</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/generated/openapi/openApiSpec.yaml</inputSpec>
                <language>html2</language>
                <output>${project.basedir}/generated/openapi</output>
            </configuration>
        </execution>
    </executions>
</plugin>

Answer 2

除了获取运行的服务以便我可以使用 spring-doc 插件外，我找不到任何解决方案。甚至尝试深入研究 spring-doc 和 swagger-maven-plugin 代码。我设法找出一个 Spring 配置，让我在没有任何外部依赖的情况下启动服务。

配置更改：

spring.cloud.config.failFast=假
spring.main.lazy-初始化=true
在数据库配置中添加了@Profile({"!generate-swagger"}) class（然后运行带有 generate-swagger 配置文件的插件）

如何在不启动服务的情况下在 WebFlux 项目中生成 OpenAPI 规范作为 Maven 构建的一部分

How to generate OpenAPI specification in WebFlux project as part of maven build without starting service

swagger

spring-webflux

openapi

springdoc