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

Question

We are using SpringDoc in our WebFlux project to annotate our APIs and serve OpenAPI documentation from a UI. However, now we need the OpenAPI file generated as part of the maven build.

SpringDoc has a plugin to fetch the file from a running service, where the service has been started by spring plugin, but our service requires a lot of stuff to be set up in order to run. We are doing this setup in our tests' @BeforeClass and don't want to extract that setup (and the corresponding cleanup) just so that the service can be started as part of the maven build. Plus we plan to eventually stop starting up the service for our tests and instead use mocks, so adding a test to retrieve the file from the running test is only a temporary solution (would like to not have to maintain startup code just in order to retrieve the OpenAPI doc).

I have tried using the swagger-maven-plugin from swagger-core, but it seems to require jaxrs, which we are not using. I have also looked into SpringFox, but it also does not offer the desired functionality.

Any ideas on how to generate OpenAPI documentation for a WebFlux project as part of the maven build without starting the service?

For the plugin from swaggerr-core project, I don't really think it requires Jaxrs to work. Maybe try using the plugin without the Jaxrs dependency. — Debargha Roy
I tried for almost a day to get it to work in our project, but wasn't able to get it to resolve any annotations, it was just generating a spec without any paths — Troy Nechanicky
After half a day I figured out how to disable enough stuff in our spring configuration to allow the service to start up without its dependencies on other services. Will create an answer with specifics shortly — Troy Nechanicky

Debargha Roy Debargha Roy · Accepted Answer · 2020-12-03T05:00:17

You can try using the below OpenAPI Maven Plugin from the OpenAPI Tools project. The advantage it offers is, it works even when you run your build without tests and as long as there are no compile errors.

<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>[email protected]</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>

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

2 Answers