Support Helidon SE 4 generation (clients and servers) (#19150)

* Save work-in-progress

* Incoming param handling generating well exc. for file upload

* Revise generated test for v3 vs v4 differences

* Leave details of multi-part handling to the user for now

* change default version to use the highest version known

* SE client changes for Helidon 4

* A few fixes; add new v4 SE samples

* Fix v3/v4 routing prep

* Improve version handling if web site is inaccessible; add test

* Reworking parameter conversion and required and validation handling

* Add generation of a return value record per response for each operation

* Improvements to the result record generation

* More changes

* Remove change in whitespace in v3 output

* More progress on parameter handling

* WIP - refactor parameter-returning methods to inner class along with return records

* Reorg of op helpers

* Use no-op for handling map in path, query, header, cookie - need to revise later

* Binary form param handling

* Clean-up and consistency check bt useAbstractClass and not

* Improve result builders

* Add new samples files

* Fix a few issues

* Update samples after rebase; add build steps for v3 and v4 uac github actions

* Remove v3 se useAbstractClass test - creates some bad code

* Generated doc updates

* Fix missing newline

* Improve Javadoc for generated Result; add convenience Result.send method

* Add bean val. for body param if needed

* Restructure generated records for declared responses; add Generated annotation selectively

* Fix typo

* In sample generation, force a stable generatorVersion value to avoid confusing builds and up-to-date samples checking

* Fix up white space in older generation

* Generate PartsUtils only with useAbstractClass = true

* Adopt some review comments; more to come

* Review comments; notably, switch to using the first path segment to group operations rather than the tags items

* Improve status handling a bit

* Add new generated sample files

* Add missing new samples files

* Quite a few updates, esp. to generated samples

* New config file for sample

* Updates samples

* Add updates to .openapi-generator/FILES contents

Author: tjquinno

.github/workflows/samples-java-helidon-v4.yaml

@@ -18,7 +18,10 @@ jobs:
       matrix:
         sample:
           - samples/client/petstore/java-helidon-client/v4/mp
+          - samples/client/petstore/java-helidon-client/v4/se
           - samples/server/petstore/java-helidon-server/v4/mp
+          - samples/server/petstore/java-helidon-server/v4/se
+          - samples/server/petstore/java-helidon-server/v4/se-uac
         version: [21]
     steps:
       - uses: actions/checkout@v4

.github/workflows/samples-jdk21.yaml

@@ -4,14 +4,18 @@ on:
     paths:
       # clients
       - samples/client/petstore/java-helidon-client/v4/mp/**
+      - samples/client/petstore/java-helidon-client/v4/se/**
       # servers
       - samples/server/petstore/java-helidon-server/v4/mp/**
+      - samples/server/petstore/java-helidon-server/v4/se/**
   pull_request:
     paths:
       # clients
       - samples/client/petstore/java-helidon-client/v4/mp/**
+      - samples/client/petstore/java-helidon-client/v4/se/**
       # servers
       - samples/server/petstore/java-helidon-server/v4/mp/**
+      - samples/server/petstore/java-helidon-server/v4/se/**
 jobs:
   build:
     name: Build with JDK21
@@ -22,8 +26,10 @@ jobs:
         sample:
           # clients
           - samples/client/petstore/java-helidon-client/v4/mp/
+          - samples/client/petstore/java-helidon-client/v4/se/
           # servers
           - samples/server/petstore/java-helidon-server/v4/mp/
+          - samples/server/petstore/java-helidon-server/v4/se/
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4

bin/configs/java-helidon-client-mp_4.yaml

@@ -3,7 +3,7 @@ library: mp
 outputDir: samples/client/petstore/java-helidon-client/v4/mp
 inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml
 additionalProperties:
-  helidonVersion: 4.0.8
+  helidonVersion: 4.0.11
   artifactId: petstore-helidon-client-mp
   hideGenerationTimestamp: "true"
   configureAuth: "false"

bin/configs/java-helidon-client-se_4.yaml

@@ -0,0 +1,14 @@
+generatorName: java-helidon-client
+library: se
+outputDir: samples/client/petstore/java-helidon-client/v4/se
+inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml
+additionalProperties:
+  helidonVersion: 4.0.11
+  artifactId: petstore-helidon-client-se
+  hideGenerationTimestamp: "true"
+  configureAuth: "false"
+  build: "all"
+  test: "spock"
+  requiredPropertiesInConstructor: "false"
+  visitable: "true"
+  fullProject: "true"

bin/configs/java-helidon-server-mp_4.yaml

@@ -4,7 +4,7 @@ outputDir: samples/server/petstore/java-helidon-server/v4/mp
 inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml
 templateDir: modules/openapi-generator/src/main/resources/java-helidon/server
 additionalProperties:
-  helidonVersion: 4.0.8
+  helidonVersion: 4.0.11
   artifactId: petstore-helidon-server-mp
   hideGenerationTimestamp: "true"
   build: "all"

bin/configs/java-helidon-server-se_4-uac-group-by-file-path.yaml

@@ -0,0 +1,13 @@
+generatorName: java-helidon-server
+library: se
+outputDir: samples/server/petstore/java-helidon-server/v4/se-uac-group-by-file-path
+inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml
+templateDir: modules/openapi-generator/src/main/resources/java-helidon/server
+additionalProperties:
+  helidonVersion: 4.0.11
+  artifactId: petstore-helidon-server-se
+  hideGenerationTimestamp: "true"
+  fullProject: "true"
+  useAbstractClass: "true"
+  generatorVersion: "stable"
+  x-helidon-groupBy: first-path-segment

bin/configs/java-helidon-server-se_4-uac.yaml

@@ -0,0 +1,12 @@
+generatorName: java-helidon-server
+library: se
+outputDir: samples/server/petstore/java-helidon-server/v4/se-uac
+inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml
+templateDir: modules/openapi-generator/src/main/resources/java-helidon/server
+additionalProperties:
+  helidonVersion: 4.0.11
+  artifactId: petstore-helidon-server-se
+  hideGenerationTimestamp: "true"
+  fullProject: "true"
+  useAbstractClass: "true"
+  generatorVersion: "stable"

bin/configs/java-helidon-server-se_4.yaml

@@ -0,0 +1,12 @@
+generatorName: java-helidon-server
+library: se
+outputDir: samples/server/petstore/java-helidon-server/v4/se
+inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml
+templateDir: modules/openapi-generator/src/main/resources/java-helidon/server
+additionalProperties:
+  helidonVersion: 4.0.11
+  artifactId: petstore-helidon-server-se
+  hideGenerationTimestamp: "true"
+  fullProject: "true"
+  x-helidon-useOptional: "true"
+  generatorVersion: "stable"

docs/generators/java-helidon-client.md

@@ -65,6 +65,8 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |useJakartaEe|whether to use Jakarta EE namespace instead of javax| |false|
 |useOneOfInterfaces|whether to use a java interface to describe a set of oneOf options, where each option is a class that implements the interface| |false|
 |withXml|whether to include support for application/xml content type and include XML annotations in the model (works with libraries that provide support for JSON and XML)| |false|
+|x-helidon-groupBy|Selects how to group operations into APIs|<dl><dt>**tags**</dt><dd>Use the 'tags' settings on each operation</dd><dt>**first-path-segment**</dt><dd>Use the first segment of the path</dd></dl>|tags|
+|x-helidon-useOptional|Wrap optional parameters in an Optional (Helidon 4 and later)| |true|
 
 ## SUPPORTED VENDOR EXTENSIONS
 

docs/generators/java-helidon-server.md

@@ -68,6 +68,8 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |useJakartaEe|whether to use Jakarta EE namespace instead of javax| |false|
 |useOneOfInterfaces|whether to use a java interface to describe a set of oneOf options, where each option is a class that implements the interface| |false|
 |withXml|whether to include support for application/xml content type and include XML annotations in the model (works with libraries that provide support for JSON and XML)| |false|
+|x-helidon-groupBy|Selects how to group operations into APIs|<dl><dt>**tags**</dt><dd>Use the 'tags' settings on each operation</dd><dt>**first-path-segment**</dt><dd>Use the first segment of the path</dd></dl>|tags|
+|x-helidon-useOptional|Wrap optional parameters in an Optional (Helidon 4 and later)| |true|
 
 ## SUPPORTED VENDOR EXTENSIONS
 

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaHelidonClientCodegen.java

@@ -65,6 +65,7 @@ public class JavaHelidonClientCodegen extends JavaHelidonCommonCodegen {
 
     private static final String X_HELIDON_REQUIRED_IMPL_IMPORTS = "x-helidon-requiredImplImports";
     private static final String X_HELIDON_IMPL_IMPORTS = "x-helidon-implImports";
+    private static final String X_CLIENT_STYLE_V3 = "x-helidon-client-style-v3";
     public static final String CONFIG_KEY = "configKey";
 
     @Setter protected String configKey = null;
@@ -173,6 +174,8 @@ public String apiFilename(String templateName, String tag) {
     public void processOpts() {
         super.processOpts();
 
+        // Not intended for users to set; we compute this based on the major version.
+        additionalProperties.put(X_CLIENT_STYLE_V3, helidonMajorVersion == 3);
         convertPropertyToStringAndWriteBack(SERIALIZATION_LIBRARY, this::setSerializationLibrary);
 
         convertPropertyToStringAndWriteBack(CONFIG_KEY, this::setConfigKey);
@@ -199,7 +202,12 @@ public void processOpts() {
         } else if (isLibrary(HELIDON_SE)) {
             apiTemplateFiles.put("api_impl.mustache", ".java");
             importMapping.put("StringJoiner", "java.util.StringJoiner");
-            importMapping.put("WebClientRequestHeaders", "io.helidon.webclient.WebClientRequestHeaders");
+            if (helidonMajorVersion == 3) {
+                importMapping.put("WebClientRequestHeaders", "io.helidon.webclient.WebClientRequestHeaders");
+            } else {
+                importMapping.put("ClientRequestHeaders", "io.helidon.http.ClientRequestHeaders");
+                importMapping.put("HeaderNames", "io.helidon.http.HeaderNames");
+            }
             importMapping.put("Pair", invokerPackage + ".Pair");
 
 
@@ -309,7 +317,10 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
             requiredImplImports.add("Pair");
         }
         if (op.getHasHeaderParams()) {
-            requiredImplImports.add("WebClientRequestHeaders");
+            requiredImplImports.add(helidonMajorVersion == 3 ? "WebClientRequestHeaders" : "ClientRequestHeaders");
+            if (helidonMajorVersion > 3) {
+                requiredImplImports.add("HeaderNames");
+            }
         }
         if (op.getHasFormParams()) {
             requiredImplImports.add("StringJoiner");