diff --git a/README.md b/README.md index cdfd50dd..d5262bbf 100644 --- a/README.md +++ b/README.md @@ -3,61 +3,140 @@ 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 + + io.github.chrimle + openapi-to-java-records-mustache-templates + 1.8.0 + +``` -## 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 ``-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 `` to the directory path. Example: +```xml + + + + org.openapitools + openapi-generator-maven-plugin + + + + generate + + + + + + + + + + + +``` +## Additional Configurations +The generated classes are customizable by using ``-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 + + DTO + + + true + + + +``` + +> [!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 `` has been set, the generated classes should be found under `./target/generated-sources/openapi`. ```java package io.github.chrimle.example; @@ -65,34 +144,57 @@ 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 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 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 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 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 ``-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) @@ -100,78 +202,10 @@ public record Example( - [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 - - io.github.chrimle - openapi-to-java-records-mustache-templates - - -``` - -- ### 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 - - io.github.chrimle - openapi-to-java-records-mustache-templates - - -``` - -- ### 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 `` to the directory path. Example: -```xml - - - - openapi-generator-maven-plugin - - - - - ${project.basedir}/src/main/resources/templates - - - - - - -``` -### 3. Review other ``-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 `` 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