Installation Guide

Java annotation processing is a concept from the Java language. There are multiple ways to integrate the OAS Generator into your project.

Dependency

The following examples use the oas-generator-spring-web. The installation of the oas-generator-jaxrs or oas-generator-schema module follows the same steps.

Apache Maven

Include via dependency

The simplest way to integrate the OAS Generator is to add the following dependency:

<dependency>
    <groupId>com.github.chhorz</groupId>
    <artifactId>oas-generator-spring-web</artifactId>
    <version>${oas-generator.version}</version>
    <scope>provided</scope>
</dependency>

Maven Compiler Plugin

Another way to include an annotation processor is the maven-compiler-plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths> (1)
            <path>
                <groupId>com.github.chhorz</groupId>
                <artifactId>oas-generator-spring-web</artifactId>
                <version>${oas-generator.version}</version>
            </path>
            <!-- ... more ... -->
        </annotationProcessorPaths>
        <annotationProcessors> (2)
            <annotationProcessor>com.github.chhorz.openapi.spring.SpringWebOpenApiProcessor</annotationProcessor>
            <!-- ... more ... -->
        </annotationProcessors>
    </configuration>
</plugin>

  1. Plugin documentation: annotationProcessorPaths

  2. Plugin documentation: annotationProcessors

It is not possible to mix this way of annotation processor integration with the dependency based one shown above.

Kotlin Maven Plugin

The plugin documentation for Kotlin Maven projects and annotation processors using kapt can be found here. For the following use case the oas-generator-* was added as dependency.

Resolution of the oas-generator.yml property file is broken for versions previous than 0.2.2.

 
<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>kapt</id>
            <goals>
                <goal>kapt</goal> (1)
            </goals>
        </execution>
    </executions>
    <configuration>
        <!-- ... -->
        <annotationProcessorArgs>
            <arg>propertiesPath=${project.basedir}/src/main/resources/oas-generator.yml</arg> (2)
            <arg>version=${project.version}</arg>
        </annotationProcessorArgs>
    </configuration>
    <!-- ... -->
</plugin>

  1. Annotation processing for Kotlin is provided by kapt

  2. Definition of the default properties file src/main/resources/oas-generator.yml does not work for Kotlin projects. The full path to the properties file must be specified.

Gradle

Gradle installation steps may be added soon.

Others

Others options may be added soon.

Configuration

Beside the configuration of the dependencies mentioned above, some additional configuration need to be done. The complete list of possible properties can be found at the corresponding section of the reference documentation. The project serves a custom JSON Schema for the configuration file, that can be included in an IDE to gain auto-completion.

Snapshots

Snapshots are available from the Sonatype OSS Snapshots repository. To configure the repository for your project to use the latest snapshot versions you have to add the following repository to your maven pom:

<repositories>
    <repository>
        <id>ossrh</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
</repositories>