Skip to content

Commit

Permalink
Update Instructions and Examples in README.md (#144)
Browse files Browse the repository at this point in the history 
* Streamline `README.md`

* Update example OpenAPI and generated record
  • Loading branch information
@Chrimle
Chrimle authored Oct 11, 2024
1 parent 14c9626 commit 05f77ab
Showing 1 changed file with 159 additions and 125 deletions.
284 changes: 159 additions & 125 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,175 +3,209 @@
Project containing [Mustache-templates](https://mustache.github.io/) used by [openapi-generator-maven-plugin](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md) to generate [Java Records](https://docs.oracle.com/en/java/javase/17/language/records.html) from [OpenAPI Specifications](https://swagger.io/specification/).

This project contains the **mustache templates**.
> [!NOTE]
> There is also an example OpenAPI Specification which will generate example Java classes (Records & Enums).
> **This is for testing purposes only**, and will **not** be included when importing the project. The templates
> support a variety of different properties and configurations. Just for reference, generated classes can be found
> under [/target/generated-sources/...](./target/generated-sources/openapi/src/src/gen/java/main/io/github/chrimle/example).

# Example
# Getting Started
The mustache templates can be acquired through multiple ways.
- [Maven Central Repository](https://central.sonatype.com/artifact/io.github.chrimle/openapi-to-java-records-mustache-templates)
- [GitHub Packages](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/packages/)
- Downloading them manually from [GitHub](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/tree/main/src/main/resources/templates)

The following is an example of a Java record generated from an OpenAPI Specification, with default `openapi-generator-maven-plugin`-configurations.
## Import Dependency
```xml
<dependency>
<groupId>io.github.chrimle</groupId>
<artifactId>openapi-to-java-records-mustache-templates</artifactId>
<version>1.8.0</version>
</dependency>
```

## Maven
> [!IMPORTANT]
> Some `openapi-generator-maven-plugin`-configuration options have not yet been verified. By using them, they may either be ignored or may even cause issues.
>
> Due to the sheer number of `<configuration>`-options, this section has been moved to the Wiki-page: [Supported 'openapi‐generator‐maven‐plugin' Configuration options
](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/wiki/Supported-%27openapi‐generator‐maven‐plugin%27-Configuration-options)
## Use the `.mustache` templates when generating
Place the file(s) in desired directory. Then, in the Maven build configuration, set the property `<templateDirectory>` to the directory path. Example:
```xml
<build>
<plugins>
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec><!-- Relative directory path to the openapi.yaml file --></inputSpec>
<templateDirectory><!-- Relative directory path to the mustache templates --></templateDirectory>
<output><!-- Relative directory path to where generated classes should be placed --></output>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
```
## Additional Configurations
The generated classes are customizable by using `<configuration>`-properties.

In this example, each generated class will be named with the suffix "DTO", and fields of generated records will be annotated with [Jakarta Bean Validation annotations](https://jakarta.ee/specifications/bean-validation/3.0/jakarta-bean-validation-spec-3.0.html#builtinconstraints).
```xml
<configuration>
<modelNameSuffix>DTO</modelNameSuffix>
<!-- ... more configurations ... -->
<configOptions>
<useBeanValidation>true</useBeanValidation>
<!-- ... more configOptions ... -->
</configOptions>
</configuration>
```

> [!TIP]
> See [Supported 'openapi‐generator‐maven‐plugin' Configuration options](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/wiki/Supported-%27openapi‐generator‐maven‐plugin%27-Configuration-options)
## OpenAPI Specification

```yaml
components:
schemas:
Example:
description: This is an example
Person:
description: Personal information
deprecated: true
type: object
required:
- fullName
- age
- gender
- height
- ssn
- aliases
- trackingCode
properties:
text:
description: Example text property
fullName:
description: Full name
type: string
nullableText:
description: Example nullable text property with default value
minLength: 2
maxLength: 50
age:
description: Age (years)
type: integer
minimum: 0
maximum: 100
gender:
$ref: '#/components/schemas/Gender'
height:
description: Height (m)
type: number
pattern: float
minimum: 0
ssn:
description: Social Security Number
type: string
default: someDefaultValue
nullable: true
collection:
description: Example list property
pattern: '^\d{3}-\d{2}-\d{4}$'
aliases:
description: Known Aliases
type: array
uniqueItems: true
minItems: 1
maxItems: 3
items:
type: integer
composite:
$ref: '#/components/schemas/Composite'
Composite:
description: This is a composite object
type: object
properties:
text:
description: Example text property
type: string
telephoneNumber:
description: Telephone Number
type: string
nullable: true
trackingCode:
description: Tracking code for Web analytics
type: string
default: "utm_source=default"
Gender:
description: Gender
type: string
enum:
- Male
- Female
```
> [!TIP]
> See [Supported OpenAPI Specification properties](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/wiki/Supported-OpenAPI-Specification-properties)
## Generate models
Compile the project, for example via:
```console
mvn compile
```
> [!IMPORTANT]
> See the complete list of [Supported OpenAPI Specification properties](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/wiki/Supported-OpenAPI-Specification-properties)
> on the wiki!

## Java Record
> [!TIP]
> Further information about how to generate models can be found on [openapi-generator-maven-plugin](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md).
## Generated Java Record
Unless the configuration property `<output>` has been set, the generated classes should be found under `./target/generated-sources/openapi`.

```java
package io.github.chrimle.example;

import ...;

/**
* This is an example
* Personal information
*
* @deprecated
* @param text Example text property
* @param nullableText Example nullable text property with default value
* @param collection Example list property
* @param composite Composite
* @param fullName Full name
* @param age Age (years)
* @param gender GenderDTO
* @param height Height (m)
* @param ssn Social Security Number
* @param aliases Known Aliases
* @param telephoneNumber Telephone Number
* @param trackingCode Tracking code for Web analytics
*/
@Deprecated
public record Example(
@javax.annotation.Nonnull String text,
@javax.annotation.Nullable String nullableText,
@javax.annotation.Nonnull List<Integer> collection,
@javax.annotation.Nonnull Composite composite) {

public Example(
@javax.annotation.Nonnull final String text,
@javax.annotation.Nullable final String nullableText,
@javax.annotation.Nullable final List<Integer> collection,
@javax.annotation.Nonnull final Composite composite) {
this.text = text;
this.nullableText = Objects.requireNonNullElse(nullableText, "someDefaultValue");
this.collection = Objects.requireNonNullElse(collection, new ArrayList<>());
this.composite = composite;
public record PersonDTO(
@javax.annotation.Nonnull @NotNull @Size(min = 2, max = 50) String fullName,
@javax.annotation.Nonnull @NotNull @Min(0) @Max(100) Integer age,
@javax.annotation.Nonnull @NotNull GenderDTO gender,
@javax.annotation.Nonnull @NotNull @DecimalMin("0") BigDecimal height,
@javax.annotation.Nonnull @NotNull @Pattern(regexp = "^\\d{3}-\\d{2}-\\d{4}$") String ssn,
@javax.annotation.Nonnull @NotNull @Size(min = 1, max = 3) Set<String> aliases,
@javax.annotation.Nullable String telephoneNumber,
@javax.annotation.Nonnull @NotNull String trackingCode) {

public PersonDTO(
@javax.annotation.Nonnull final String fullName,
@javax.annotation.Nonnull final Integer age,
@javax.annotation.Nonnull final GenderDTO gender,
@javax.annotation.Nonnull final BigDecimal height,
@javax.annotation.Nonnull final String ssn,
@javax.annotation.Nullable final Set<String> aliases,
@javax.annotation.Nullable final String telephoneNumber,
@javax.annotation.Nullable final String trackingCode) {
this.fullName = fullName;
this.age = age;
this.gender = gender;
this.height = height;
this.ssn = ssn;
this.aliases = Objects.requireNonNullElse(aliases, new LinkedHashSet<>());
this.telephoneNumber = telephoneNumber;
this.trackingCode = Objects.requireNonNullElse(trackingCode, "utm_source=default");
}
}
```

## Further examples
All supported plugin `<configuration>`-options and OpenAPI Specification-properties have been tested.
For reference:
- [OpenAPI Specification](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/blob/main/src/main/resources/api.yaml), used for all tests
- [Maven plugin executions](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/blob/main/pom.xml#L166), for each different set of configurations
- [Generated classes](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/tree/main/target/generated-sources/openapi/src/src/gen/java/main/io/github/chrimle/example) grouped by plugin-execution.

### Useful Resources

- [Maven in 5 minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html)
- [OpenAPI Basic Structure](https://swagger.io/docs/specification/basic-structure/)
- [openapi-generator-maven-plugin](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md)
- [Mustache](https://mustache.github.io/)

# How-to Instructions
> [!NOTE]
> This project is about mustache templates only. For that reason, any other files or configurations are either irrelevant, or may not be applicable to your use-case.
## 1. Get mustache templates
The mustache templates can be acquired through multiple ways.
- ### Import from [Maven Central Repository](https://central.sonatype.com/artifact/io.github.chrimle/openapi-to-java-records-mustache-templates)
Import the project via:
```xml
<dependency>
<groupId>io.github.chrimle</groupId>
<artifactId>openapi-to-java-records-mustache-templates</artifactId>
<version><!-- Insert version here --></version>
</dependency>
```

- ### Import from [GitHub Packages](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/packages/)
> [!IMPORTANT]
> Importing via GitHub Packages require authentication, see [GitHub Packages: Installing a Package](https://docs.github.com/en/packages/learn-github-packages/installing-a-package) for further details.
Import the project via:
```xml
<dependency>
<groupId>io.github.chrimle</groupId>
<artifactId>openapi-to-java-records-mustache-templates</artifactId>
<version><!-- Insert version here --></version>
</dependency>
```

- ### Browse mustache templates on GitHub
The mustache templates can be found under [./src/main/resources/templates](./src/main/resources/templates).

## 2. Use the `.mustache` templates when generating
Place the file(s) in desired directory. Then, in the Maven build configuration, set the property `<templateDirectory>` to the directory path. Example:
```xml
<build>
<plugins>
<plugin>
<artifactId>openapi-generator-maven-plugin</artifactId>
<!-- ... -->
<executions>
<execution>
<configuration>
<templateDirectory>${project.basedir}/src/main/resources/templates</templateDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
```
### 3. Review other `<configuration>`-properties & OpenAPI Specification
> [!IMPORTANT]
> Review the configurations, and compare with [Supported Configurations](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/wiki/Supported-%27openapi‐generator‐maven‐plugin%27-Configuration-options).
> Do the same with the OpenAPI Specification, and [Supported OpenAPI Spec Properties](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/wiki/Supported-OpenAPI-Specification-properties).
### 4. Generate models
Compile the project, for example via:
```console
mvn compile
```

> [!TIP]
> Further information about how to generate models can be found on [openapi-generator-maven-plugin](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md).
### 5. Verify models
Unless the configuration property `<output>` has been set, the generated classes should be found under `./target/generated-sources/openapi`.

### 6. Encountered an issue?
## Encountered an issue?
Double-check that build-configurations and the OpenAPI Specification is supported. If problems persist, check the [open issues](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/issues).
If the problem you are facing is not already reported, please [open an issue](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/issues/new) with details and instructions to reproduce.


# License
MIT License

Expand Down

0 comments on commit 05f77ab

Please sign in to comment.