Skip to content

Commit 05f77ab

Browse files
ChrimleChrimle
authored
Update Instructions and Examples in README.md (#144)
* Streamline `README.md` * Update example OpenAPI and generated record
1 parent 14c9626 commit 05f77ab

File tree

1 file changed

+159
-125
lines changed

1 file changed

+159
-125
lines changed

‎README.md

Lines changed: 159 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -3,175 +3,209 @@
33
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/).
44

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

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

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

16-
## Maven
17-
> [!IMPORTANT]
18-
> 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.
19-
>
20-
> Due to the sheer number of `<configuration>`-options, this section has been moved to the Wiki-page: [Supported 'openapi‐generator‐maven‐plugin' Configuration options
21-
](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/wiki/Supported-%27openapi‐generator‐maven‐plugin%27-Configuration-options)
22+
## Use the `.mustache` templates when generating
23+
Place the file(s) in desired directory. Then, in the Maven build configuration, set the property `<templateDirectory>` to the directory path. Example:
24+
```xml
25+
<build>
26+
<plugins>
27+
<plugin>
28+
<groupId>org.openapitools</groupId>
29+
<artifactId>openapi-generator-maven-plugin</artifactId>
30+
<executions>
31+
<execution>
32+
<goals>
33+
<goal>generate</goal>
34+
</goals>
35+
<configuration>
36+
<inputSpec><!-- Relative directory path to the openapi.yaml file --></inputSpec>
37+
<templateDirectory><!-- Relative directory path to the mustache templates --></templateDirectory>
38+
<output><!-- Relative directory path to where generated classes should be placed --></output>
39+
</configuration>
40+
</execution>
41+
</executions>
42+
</plugin>
43+
</plugins>
44+
</build>
45+
```
46+
## Additional Configurations
47+
The generated classes are customizable by using `<configuration>`-properties.
48+
49+
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).
50+
```xml
51+
<configuration>
52+
<modelNameSuffix>DTO</modelNameSuffix>
53+
<!-- ... more configurations ... -->
54+
<configOptions>
55+
<useBeanValidation>true</useBeanValidation>
56+
<!-- ... more configOptions ... -->
57+
</configOptions>
58+
</configuration>
59+
```
60+
61+
> [!TIP]
62+
> 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)
2263
2364
## OpenAPI Specification
2465

2566
```yaml
2667
components:
2768
schemas:
28-
Example:
29-
description: This is an example
69+
Person:
70+
description: Personal information
3071
deprecated: true
3172
type: object
73+
required:
74+
- fullName
75+
- age
76+
- gender
77+
- height
78+
- ssn
79+
- aliases
80+
- trackingCode
3281
properties:
33-
text:
34-
description: Example text property
82+
fullName:
83+
description: Full name
3584
type: string
36-
nullableText:
37-
description: Example nullable text property with default value
85+
minLength: 2
86+
maxLength: 50
87+
age:
88+
description: Age (years)
89+
type: integer
90+
minimum: 0
91+
maximum: 100
92+
gender:
93+
$ref: '#/components/schemas/Gender'
94+
height:
95+
description: Height (m)
96+
type: number
97+
pattern: float
98+
minimum: 0
99+
ssn:
100+
description: Social Security Number
38101
type: string
39-
default: someDefaultValue
40-
nullable: true
41-
collection:
42-
description: Example list property
102+
pattern: '^\d{3}-\d{2}-\d{4}$'
103+
aliases:
104+
description: Known Aliases
43105
type: array
106+
uniqueItems: true
107+
minItems: 1
108+
maxItems: 3
44109
items:
45-
type: integer
46-
composite:
47-
$ref: '#/components/schemas/Composite'
48-
Composite:
49-
description: This is a composite object
50-
type: object
51-
properties:
52-
text:
53-
description: Example text property
110+
type: string
111+
telephoneNumber:
112+
description: Telephone Number
54113
type: string
114+
nullable: true
115+
trackingCode:
116+
description: Tracking code for Web analytics
117+
type: string
118+
default: "utm_source=default"
119+
Gender:
120+
description: Gender
121+
type: string
122+
enum:
123+
- Male
124+
- Female
125+
```
126+
> [!TIP]
127+
> See [Supported OpenAPI Specification properties](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/wiki/Supported-OpenAPI-Specification-properties)
128+
129+
## Generate models
130+
Compile the project, for example via:
131+
```console
132+
mvn compile
55133
```
56-
> [!IMPORTANT]
57-
> See the complete list of [Supported OpenAPI Specification properties](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/wiki/Supported-OpenAPI-Specification-properties)
58-
> on the wiki!
59134

60-
## Java Record
135+
> [!TIP]
136+
> 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).
137+
138+
## Generated Java Record
139+
Unless the configuration property `<output>` has been set, the generated classes should be found under `./target/generated-sources/openapi`.
61140

62141
```java
63142
package io.github.chrimle.example;
64143

65144
import ...;
66145

67146
/**
68-
* This is an example
147+
* Personal information
69148
*
70149
* @deprecated
71-
* @param text Example text property
72-
* @param nullableText Example nullable text property with default value
73-
* @param collection Example list property
74-
* @param composite Composite
150+
* @param fullName Full name
151+
* @param age Age (years)
152+
* @param gender GenderDTO
153+
* @param height Height (m)
154+
* @param ssn Social Security Number
155+
* @param aliases Known Aliases
156+
* @param telephoneNumber Telephone Number
157+
* @param trackingCode Tracking code for Web analytics
75158
*/
76159
@Deprecated
77-
public record Example(
78-
@javax.annotation.Nonnull String text,
79-
@javax.annotation.Nullable String nullableText,
80-
@javax.annotation.Nonnull List<Integer> collection,
81-
@javax.annotation.Nonnull Composite composite) {
82-
83-
public Example(
84-
@javax.annotation.Nonnull final String text,
85-
@javax.annotation.Nullable final String nullableText,
86-
@javax.annotation.Nullable final List<Integer> collection,
87-
@javax.annotation.Nonnull final Composite composite) {
88-
this.text = text;
89-
this.nullableText = Objects.requireNonNullElse(nullableText, "someDefaultValue");
90-
this.collection = Objects.requireNonNullElse(collection, new ArrayList<>());
91-
this.composite = composite;
160+
public record PersonDTO(
161+
@javax.annotation.Nonnull @NotNull @Size(min = 2, max = 50) String fullName,
162+
@javax.annotation.Nonnull @NotNull @Min(0) @Max(100) Integer age,
163+
@javax.annotation.Nonnull @NotNull GenderDTO gender,
164+
@javax.annotation.Nonnull @NotNull @DecimalMin("0") BigDecimal height,
165+
@javax.annotation.Nonnull @NotNull @Pattern(regexp = "^\\d{3}-\\d{2}-\\d{4}$") String ssn,
166+
@javax.annotation.Nonnull @NotNull @Size(min = 1, max = 3) Set<String> aliases,
167+
@javax.annotation.Nullable String telephoneNumber,
168+
@javax.annotation.Nonnull @NotNull String trackingCode) {
169+
170+
public PersonDTO(
171+
@javax.annotation.Nonnull final String fullName,
172+
@javax.annotation.Nonnull final Integer age,
173+
@javax.annotation.Nonnull final GenderDTO gender,
174+
@javax.annotation.Nonnull final BigDecimal height,
175+
@javax.annotation.Nonnull final String ssn,
176+
@javax.annotation.Nullable final Set<String> aliases,
177+
@javax.annotation.Nullable final String telephoneNumber,
178+
@javax.annotation.Nullable final String trackingCode) {
179+
this.fullName = fullName;
180+
this.age = age;
181+
this.gender = gender;
182+
this.height = height;
183+
this.ssn = ssn;
184+
this.aliases = Objects.requireNonNullElse(aliases, new LinkedHashSet<>());
185+
this.telephoneNumber = telephoneNumber;
186+
this.trackingCode = Objects.requireNonNullElse(trackingCode, "utm_source=default");
92187
}
93188
}
94189
```
95190

191+
## Further examples
192+
All supported plugin `<configuration>`-options and OpenAPI Specification-properties have been tested.
193+
For reference:
194+
- [OpenAPI Specification](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/blob/main/src/main/resources/api.yaml), used for all tests
195+
- [Maven plugin executions](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/blob/main/pom.xml#L166), for each different set of configurations
196+
- [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.
197+
96198
### Useful Resources
97199

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

103-
# How-to Instructions
104-
> [!NOTE]
105-
> 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.
106-
## 1. Get mustache templates
107-
The mustache templates can be acquired through multiple ways.
108-
- ### Import from [Maven Central Repository](https://central.sonatype.com/artifact/io.github.chrimle/openapi-to-java-records-mustache-templates)
109-
Import the project via:
110-
```xml
111-
<dependency>
112-
<groupId>io.github.chrimle</groupId>
113-
<artifactId>openapi-to-java-records-mustache-templates</artifactId>
114-
<version><!-- Insert version here --></version>
115-
</dependency>
116-
```
117-
118-
- ### Import from [GitHub Packages](https://github.com/Chrimle/openapi-to-java-records-mustache-templates/packages/)
119-
> [!IMPORTANT]
120-
> 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.
121-
122-
Import the project via:
123-
```xml
124-
<dependency>
125-
<groupId>io.github.chrimle</groupId>
126-
<artifactId>openapi-to-java-records-mustache-templates</artifactId>
127-
<version><!-- Insert version here --></version>
128-
</dependency>
129-
```
130-
131-
- ### Browse mustache templates on GitHub
132-
The mustache templates can be found under [./src/main/resources/templates](./src/main/resources/templates).
133-
134-
## 2. Use the `.mustache` templates when generating
135-
Place the file(s) in desired directory. Then, in the Maven build configuration, set the property `<templateDirectory>` to the directory path. Example:
136-
```xml
137-
<build>
138-
<plugins>
139-
<plugin>
140-
<artifactId>openapi-generator-maven-plugin</artifactId>
141-
<!-- ... -->
142-
<executions>
143-
<execution>
144-
<configuration>
145-
<templateDirectory>${project.basedir}/src/main/resources/templates</templateDirectory>
146-
</configuration>
147-
</execution>
148-
</executions>
149-
</plugin>
150-
</plugins>
151-
</build>
152-
```
153-
### 3. Review other `<configuration>`-properties & OpenAPI Specification
154-
> [!IMPORTANT]
155-
> 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).
156-
> 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).
157-
158-
### 4. Generate models
159-
Compile the project, for example via:
160-
```console
161-
mvn compile
162-
```
163-
164-
> [!TIP]
165-
> 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).
166-
167-
### 5. Verify models
168-
Unless the configuration property `<output>` has been set, the generated classes should be found under `./target/generated-sources/openapi`.
169-
170-
### 6. Encountered an issue?
205+
## Encountered an issue?
171206
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).
172207
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.
173208

174-
175209
# License
176210
MIT License
177211

0 commit comments

Comments
 (0)