Generate OpenAPI 3.0 json/yaml from Spring application sources at compile time with maven plugin

Question

I want to generate an OpenApi 3.0 definition, at compile time, using maven plugin, from existing Spring (note: NOT Boot) app sources.

I have set up io.swagger.v3.oas.annotations in controller classes like so:

package com.acme.rest;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "Dummy Controller", description = "Dummy controller.")
@RestController
@RequestMapping("/api/v1/dummy")
public class DummyController {

    @Operation(summary = "dummy(). Does litrally nothing.")
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String doStuff() {
        return "dummy";
    }
}

and tried the swagger-maven-plugin

<plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>2.2.0</version>
    <configuration>
        <outputPath>${project.build.directory}/swagger-def</outputPath>
        <resourcePackages>com.acme</resourcePackages>
        <prettyPrint>true</prettyPrint>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>resolve</goal>
            </goals>
        </execution>
    </executions>
</plugin>

however I get nothing except openapi version.

mvn clean compile , produces:

{
  "openapi" : "3.0.1"
}

---

I dug a bit through the implementation and it seems like there is no io.swagger.v3.oas.integration.api.OpenApiReader and/or io.swagger.v3.oas.integration.api.OpenApiScanner implementation to actually pick up the relevant annotations and parse them. I draw this conclusion from the fact that if I add custom implementation of them as suggested in the docs I can sources generated.

<scannerClass>com.acme.util.SwaggerOpenApiScanner</scannerClass>
<readerClass>com.acme.util.SwaggerOpenApiReader</readerClass>

I just dont understand why out of the box SWAGGER plugin does not parse SWAGGER annotations despite both of them are from the very same group io.swagger.core.v3 ?

What am I missing something? Can you recommend some alternative plugin to do this job?

Answer 1

I am using the Swagger v3 annotations in my project and I was facing the same issue.

I have found the springdoc-openapi-maven-plugin that works well with the generated Swagger docs using the springdoc-openapi-ui dependency in Maven.

Here is my configuration in Maven:

    <profiles>
        <profile>
            <id>apidoc</id>
            <dependencies>
                <dependency>
                    <groupId>org.springdoc</groupId>
                    <artifactId>springdoc-openapi-ui</artifactId>
                    <version>${springdoc-openapi-ui.version}</version>
                </dependency>
            </dependencies>

            <build>
                <plugins>

                    <plugin>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-maven-plugin</artifactId>
                        <configuration>
                            <excludes>
                                <exclude>
                                    <groupId>org.projectlombok</groupId>
                                    <artifactId>lombok</artifactId>
                                </exclude>
                            </excludes>
                            <jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments>
                        </configuration>
                        <executions>
                            <execution>
                                <id>pre-integration-test</id>
                                <goals>
                                    <goal>start</goal>
                                </goals>
                            </execution>
                            <execution>
                                <id>post-integration-test</id>
                                <goals>
                                    <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:8090/v3/api-docs.yaml</apiDocsUrl>
                            <outputFileName>openapi.yaml</outputFileName>
                            <outputDir>${project.basedir}/src/main/doc/swagger</outputDir>
                            <skip>false</skip>
                        </configuration>
                    </plugin>
                </plugins>
            </build>

        </profile>

More information on this plugin here:

• https://springdoc.org/plugins.html
• https://github.com/springdoc/springdoc-openapi-maven-plugin