Beginner Guide (Step‐by‐Step)

Table of Contents

This guide is intended to describe a step-by-step process of using the project. It will cover the following:

1. Prerequisites
   • Set up a Project (Maven)
   • Define an OpenAPI Specification
   • Set up openapi-generator-maven-plugin
2. Import openapi-to-java-records-mustache-templates as a dependency
3. Using maven-dependency-plugin to unpack mustache templates
4. Use mustache templates when generating classes
5. Generate classes via openapi-generator-maven-plugin
6. Verifying generated classes
7. Further customizations

1. Prerequisites

These will likely already be fulfilled, however, for verification/experimental purposes, minimal examples will be provided to fulfill the prerequisites.

Set up a Project (Maven)

Self-explanatory, as the intention is to use openapi-generator-maven-plugin to generate classes. No pom.xml-file will be provided as an example.

Define an OpenAPI Specification

The OpenAPI Specification (.yaml/.yml-file) is the source from which classes will be generated.

Example

openapi: 3.0.0
info:
  title: Example OpenAPI Spec.
  version: 0.0.1

servers:
  - url: http://localhost/
    description: Irrelevant

paths:
  /ignore:
    get:
      summary: Ignore
      responses:
        '200':
          description: OK

components:
  schemas:
    ExampleRecord:
      type: object
      description: Example of a Record
      properties:
        field1:
          type: boolean
          description: a Boolean field

Set up openapi-generator-maven-plugin

The project pom.xml-file should include a <build>-step using openapi-generator-maven-plugin.

Example

This should be placed within the root (<project>) property.

<build>
    <plugins>
      <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>7.8.0</version>
        <executions>
          <execution>
            <id>generate-example</id>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <generatorName>java</generatorName>
              <generateModels>true</generateModels>
              <inputSpec><!-- This is the relative path to the OpenAPI .yaml file --></inputSpec>
              <templateDirectory><!-- This is the relative path to the .mustache template files --></templateDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

2. Import openapi-to-java-records-mustache-templates as a dependency

The project is officially hosted on GitHub Packages and Maven Central Repository. Regardless, the dependency will look something like:

<dependency>
    <groupId>io.github.chrimle</groupId>
    <artifactId>openapi-to-java-records-mustache-templates</artifactId>
    <version><!-- Check for latest version --></version>
</dependency>

This will be used in the next step.

3. Using maven-dependency-plugin to unpack mustache templates

As a suggestion, maven-dependency-plugin can be used to unpack the .mustache-files from the imported artifact. For example:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-dependency-plugin</artifactId>
      <version><!-- Check for latest version --></version>
      <executions>
        <execution>
          <id>unpack-mustache-files</id>
          <phase>validate</phase>
          <goals>
            <goal>unpack</goal>
          </goals>
          <configuration>
            <artifactItems>
              <artifactItem>
                <groupId>io.github.chrimle</groupId>
                <artifactId>openapi-to-java-records-mustache-templates</artifactId>
                <version><!-- Check for latest version --></version>
                <type>jar</type>
                <overWrite>true</overWrite>
                <outputDirectory>${project.basedir}/src/main/resources</outputDirectory>
                <includes>**/*.mustache</includes>
              </artifactItem>
            </artifactItems>
          </configuration>
        </execution>
      </executions>
    </plugin>
    <!-- openapi-generator-maven-plugin goes here (Prerequisite) -->
  </plugins>
</build>

In this example, the .mustache-files will be copied into ${project.basedir}/src/main/resources.

4. Use mustache templates when generating classes

In order to use custom templates when generating via openapi-generator-maven-plugin, set the <templateDirectory>-property to the relative path location of the .mustache-files.

Tip

The <outputDirectory> (Step 3) should match the <templateDirectory>-property (Prerequisite Step 3).

5. Generate classes via openapi-generator-maven-plugin

To generate classes, compile the project via:

mvn compile

6. Verifying generated classes

Unless the <output>-property has been set in the build configuration, the generated class(es) should be found in ./target/generated-sources/openapi. The generated record class should look something like this:

/*
 * Example OpenAPI Spec.
 * An example OpenAPI-spec to generate example Java records.
 *
 * The version of the OpenAPI document: 0.0.1
 *
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
 * https://openapi-generator.tech
 * Do not edit the class manually.
 *
 * This class was generated using custom mustache templates from
 * openapi-to-java-records-mustache-templates. For further information,
 * questions, requesting features or reporting issues, please visit:
 * https://github.com/Chrimle/openapi-to-java-records-mustache-templates.
 * Generated with Version: 2.5.0
 *
 */

package org.openapitools.client.model;

import java.util.Objects;
import com.google.gson.TypeAdapter;
import com.google.gson.annotations.JsonAdapter;
import com.google.gson.annotations.SerializedName;
import com.google.gson.stream.JsonReader;
import com.google.gson.stream.JsonWriter;
import java.io.IOException;
import java.util.Arrays;

/**
 * Example of a Record
 *
 * @param field1 a Boolean field
 */
public record ExampleRecord(
    @javax.annotation.Nonnull Boolean field1) {

  public ExampleRecord(
      @javax.annotation.Nonnull final Boolean field1) { 
    this.field1 = field1;
  }
}

This concludes the guide. Preferably, verify that the generated record is correct before trying to generate classes from a larger OpenAPI Specification.

7. Further customizations

With the plugins and custom templates set up, further customizations can be made. OpenAPI Specifications has many options, but which/what/how/when it is reflected in the generated classes is primarily up to openapi-generator-maven-plugin and its many <configuration> and <configOption>-properties. Finally, depending on the generated classes, it may be dependent on openapi-to-java-records-mustache-templates. For these reasons, verify that this project supports the used properties/configurations:

• Supported OpenAPI Specification properties
• Supported 'openapi‐generator‐maven‐plugin' Configuration options

Please verify that they are listed as supported there. If not, please check if there is an open issue for it, or create one.