Beginner Guide (Step‐by‐Step)

Note

For an even easier example, refer to the tests module, which demonstrates exactly these steps described in this guide.

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.