Generate OpenAPI documentation at build/compile time in SpringBoot 3.x application

[ragro]

I am running my application on Spring Boot 3.2.4 with Java 17. For generating Swagger/OpenAPI documentation, I am using Springdoc-OpenApi version 2.5.0. I came across the springdoc-openapi-maven-plugin which can generate the documentation, but it starts the application, generates the OpenAPI documentation, and then stops the application. This behavior is not suitable for my use case. I want to generate the OpenAPI documentation at build time without starting the application in any way.

Below is the dependencies I added in pom.xml :

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

  <!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotations -->
  <dependency>
      <groupId>io.swagger.core.v3</groupId>
      <artifactId>swagger-annotations</artifactId>
      <version>2.2.21</version>
  </dependency>

  <!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-models -->
  <dependency>
      <groupId>io.swagger.core.v3</groupId>
      <artifactId>swagger-models</artifactId>
      <version>2.2.21</version>
  </dependency>

I have created a profile called "generate-swagger-client" and placed the necessary plugins inside it. To execute the profile, I use the command "mvn clean install -P generate-swagger-client". The command successfully generates the OpenAPI documentation, but it also starts and stops the application in the process. However, I want to generate the OpenAPI documentation at build time without starting the application.

Below is the plugins :

 <profile>
<id>generate-swagger-client</id>
<build>
    <plugins>
        <!-- Plugin for generating OpenAPI 3 documentation -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>start</goal>
                        <goal>stop</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>1.4</version>
            <executions>
                <execution>
                    <id>integration-test</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
                <outputFileName>openapi.json</outputFileName>
                <outputDir>${basedir}/generated/swagger-specs</outputDir>
                <skip>false</skip>
            </configuration>
        </plugin>
    </plugins>
</build>
 </profile>

I want to generate the OpenAPI documentation at build time without starting the application in any way. How can i fix this ?

[mnisius]

@ragro Have a look at https://github.com/stoicflame/enunciate. Its a different tool but it does what you want by design. With SpringDoc it fells like an ugly hack in my opinion. (just the get the spec during buildtime part)

[murdos]

@ragro : There's also https://github.com/kbuntrock/openapi-maven-plugin