Generate Spring source files from OpenAPI specification files

We will follow an API first approach, by defining the API in OpenAPI specification files, and then using maven plugins to generate the sources of the OpenAPI maven submodule, that will be used from our api submodule.

Versions

This approach has been tested in a Java 17 environment with spring-boot-starter-parent 3.0.4.

Resources

We will define the folder with the OpenAPI specification files as resources, so on running Maven resources:copy-resources target, resources are copied.

In our example, OpenAPI specification files are stored in src/main/resources/swagger folder, and they are copied to target/swagger folder.

OpenApi Generator Maven Plugin

The OpenAPI Generator Maven Plugin will take the OpenApi specification files and will generate the Java source files, in this case, generating Spring Boot 3 source files for Spring Controllers.

This plugin will be linked to Maven process-resources phase.

Swagger Codegen Maven Plugin

The Swagger Codegen Maven Plugin will take the OpenApi specification files and will merge them into a single specification file that will be used for Swagger Purposes.

This plugin will be linked to Maven process-resources phase.

In this case, we have generated the file into static folder, which is the default folder used by SpringDoc for searching for OpenAPI specification files. Note that we will later specify to SpringDoc the subpath of OpenAPI file with springdoc.swagger-ui.url spring property with value /anyFullSpecificationFile.yml. As long as dependency org.springdoc:springdoc-openapi-starter-webmvc-ui is set (I tested with version 2.1.0), Swagger UI will work as expected.

Configuration

See below part of Maven configuration.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
...
  <properties>
    <plugin.swagger-codegen-maven.version>3.0.46</plugin.swagger-codegen-maven.version>
    <plugin.openapi-generator-maven.version>6.3.0</plugin.openapi-generator-maven.version>

    <openapi-generator-swagger-folder-path>${project.build.directory}/swagger</openapi-generator-swagger-folder-path>
    <api-package>anyJavaPackageForApiClasses</api-package>
    <model-package>anyJavaPackageForApiModelClasses</model-package>
    <model-name-prefix>Api</model-name-prefix>
    <swagger-ui-folder>${project.build.directory}/classes/static</swagger-ui-folder>
  </properties>

  <build>
    <resources>
      <resource>
        <directory>src/main/resources/swagger</directory>
        <filtering>true</filtering>
        <targetPath>${openapi-generator-swagger-folder-path}</targetPath>
      </resource>
    </resources>
    <plugins>
      <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>${plugin.openapi-generator-maven.version}</version>
        <executions>
          <execution>
            <id>GenerateSourceFiles</id>
            <phase>process-resources</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <inputSpec>${openapi-generator-swagger-folder-path}/anySpecificationFile.yml</inputSpec>
              <generatorName>spring</generatorName>
              <apiPackage>${api-package}</apiPackage>
              <modelPackage>${model-package}</modelPackage>
              <modelNamePrefix>${model-name-prefix}</modelNamePrefix>
              <skipOverwrite>true</skipOverwrite>
              <configOptions>
                <useSpringBoot3>true</useSpringBoot3>
                <interfaceOnly>true</interfaceOnly>
                <skipDefaultInterface>true</skipDefaultInterface>
                <dateLibrary>java8</dateLibrary>
                <performBeanValidation>true</performBeanValidation>
                <serializableModel>true</serializableModel>
                <useTags>true</useTags>
              </configOptions>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>io.swagger.codegen.v3</groupId>
        <artifactId>swagger-codegen-maven-plugin</artifactId>
        <version>${plugin.swagger-codegen-maven.version}</version>
        <executions>
          <execution>
            <id>GenerateSourceFiles</id>
            <phase>process-resources</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <inputSpec>${openapi-generator-swagger-folder-path}/anySpecificationFile.yml</inputSpec>
              <language>openapi-yaml</language>
              <generateApiDocumentation>false</generateApiDocumentation>
              <generateSupportingFiles>false</generateSupportingFiles>
              <output>${swagger-ui-folder}</output>
              <configOptions>
                <outputFile>anyFullSpecificationFile.yml</outputFile>
              </configOptions>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Navigation menu