Add back and enhance the page describing OpenAPI generation for Helidon 4

docs/src/main/asciidoc/includes/attributes.adoc

@@ -281,7 +281,7 @@ endif::[]
 :micrometer-javadoc-registry-prometheus-base-url: {micrometer-javadoc-base-url}/micrometer-registry-prometheus/{version-lib-micrometer}/io/micrometer/prometheus
 
 // OpenAPI generator
-:openapi-generator-version: 6.2.1
+:openapi-generator-version: 7.6.0
 :openapi-generator-tool-base-url: https://github.com/OpenAPITools/openapi-generator
 :openapi-generator-site-version: v{openapi-generator-version}
 

docs/src/main/asciidoc/includes/openapi/openapi-generator.adoc

@@ -20,7 +20,6 @@
 :keywords: helidon, {flavor-lc}, openapi, generator
 :feature-name: Helidon {flavor-uc} OpenAPI Generator
 // DO NOT CHANGE THE FOLLOWING - it's used as a minimum release that will not normally change with new releases of the OpenAPI generator
-:first-version-with-strong-helidon-support: 6.2.1
 // Update the following when it is convenient to keep pace with the latest releases of the OpenAPITools generator
 // end::preamble[]
 
@@ -38,8 +37,8 @@ The link:{openapi-spec-url}[OpenAPI specification] provides a standard way to ex
 
 Separately, the link:{openapi-generator-tool-site-url}[OpenAPI generator] project has created a powerful code generator tool which accepts an OpenAPI document and generates client and server code for many languages and frameworks. The Helidon team contributes to this tool to ensure that it provides strong support for Helidon {flavor-uc} clients and servers.
 As a result, you can use the generator to create code that fits smoothly into your Helidon applications.
-The OpenAPI generator release {first-version-with-strong-helidon-support} gained particularly strong support for Helidon.
-This document applies to that release and later ones.
+
+Use the OpenAPI generator release {openapi-generator-version} or later which this document describes.
 
 In the vocabulary of the tool, there are two _generators_ for Helidon:
 
@@ -81,7 +80,7 @@ The rest of this document walks you through <<usage-section,how to use>> each te
 == Maven Coordinates
 Your project does not need any dependencies on the OpenAPI generator.
 
-To use the OpenAPI generator plug-in to generate or regenerate files during your project build, add the following to your project's `pom.xml` file to declare the plug-in. Choose whichever version of the generator plug-in meets your needs as long as it is at least {first-version-with-strong-helidon-support}.
+To use the OpenAPI generator plug-in to generate or regenerate files during your project build, add the following to your project's `pom.xml` file to declare the plug-in. Choose whichever version of the generator plug-in meets your needs as long as it is at least {openapi-generator-version}.
 
 [source,xml,subs="+attributes,+macros"]
 .Declaring the OpenAPI Generator Plug-in
@@ -235,7 +234,7 @@ You must specify the following options:
 |===
 
 === Recommended Settings for the OpenAPI Generator
-Your project might have different needs, but in general we advise developers to use the following settings when using the OpenAPI generator.
+Your project might have different needs, but in general we advise developers to use the following settings when using the OpenAPI generator, both from the command line and using the Maven plug-in.
 
 
 .Recommended OpenAPI Generator Additional Properties
@@ -270,6 +269,10 @@ Your project might have different needs, but in general we advise developers to
 | `artifactVersion`
 | Artifact version in the generated `pom.xml`
 | `1.0.0`
+
+| `useAbstractClass`
+| Generate server abstract classes instead of interfaces. Setting to `true` generates significantly more helpful code.
+| `false`
 |===
 
 [NOTE]
@@ -308,12 +311,13 @@ Among the many configuration settings available to you, some you should particul
 
 |Version of Helidon for which to generate the files
 | {nbsp}
-|`2.5.2`
+|Latest published Helidon release *
 a|Affects:
 
 * Helidon version for the `<parent>`
 * Dependencies (`javax` vs. `jakarta`)
 * `java import` statements in generated code (`javax` vs. `jakarta`)
+* Which Helidon APIs are used (3.x vs. 4.x, for example)
 
 |`fullProject`
 |Whether to generate all the normal files or only API files
@@ -328,11 +332,13 @@ and the model classes.
 |`jackson`
 |
 |===
+* The generator attempts to retrieve the list of released Helidon versions from the Helidon website, falling back to locally-stored Java preferences loaded from the previous generator run, and as a last resort using hard-coded values for each major Helidon release.
 
 
 // end::config[]
 
 // tag::usage[]
+// tag::usage-basics[]
 
 [[usage-section]]
 == Usage
@@ -401,15 +407,24 @@ The generator replaces the generated classes or interfaces but does not touch ot
 
 The Helidon _client_ generator always creates concrete classes. Typically, you do not need to customize the behavior in the generated client API classes. If you choose to do so, write your own subclass of the generated client API class; _do not_ modify the generated files.
 
-==== Grouping Operations into "APIs"
+// end::usage-basics[]
+// tag::usage-grouping-intro[]
+
+==== Grouping Operations into APIs
 Each operation in an OpenAPI document can have a `tags` attribute.
-The generators group operations with the same `tags` value into the same API.
+By default, the generators group operations with the same `tags` value into the same API or service. Alternatively, if you specify the option `x-helidon-groupBy` as `first-path-segment`, the generators use the first segment of the path to group operations together.
 
+// end::usage-grouping-intro[]
+// tag::usage-grouping-server[]
 When you generate a Helidon {flavor-uc} server, the generator creates a separate interface or class for each API your service _exposes_.
 You implement each interface or extend each class to add your business logic for that API.
+// end::usage-grouping-server[]
+// tag::usage-grouping-client[]
 
 When you generate a Helidon {flavor-uc} client, the generated code contains a separate API class for each distinct API your code might _invoke_.
 
+// end::usage-grouping-client[]
+// tag::usage-after-grouping[]
 [[usage-running]]
 === Running the OpenAPI Generators
 
@@ -523,6 +538,7 @@ Before you use the online generator, consider whether any of the input you provi
 
 This document does not explore further the use of the online generator.
 
+// end::usage-after-grouping[]
 // end::usage[]
 
 
@@ -537,9 +553,10 @@ The Helidon generators go a long way in helping you write your client or server.
 // tag::using-generated-code-server-intro[]
 
 === Completing the Server
-Recall from earlier how the OpenAPI generator gathers operations into one or more "APIs" and generates either a class or an interface--your choice--for each API.
+Recall from earlier how the OpenAPI generator gathers operations into one or more APIs or services and generates either an abstract class or an interface--your choice--for each API.
 You need to extend each generated API class or implement each generated API interface by writing your own classes.
-Any input parameters to the endpoints are expressed as POJO model objects or Java types, as declared in the OpenAPI document. Your server code uses each of the input parameters to accomplish whatever business purpose that endpoint is responsible for, possibly returning a result as a POJO or Java type as indicated for that operation in the OpenAPI document.
+
+Any input parameters to the operations are expressed as POJO model objects or Java types as declared in the OpenAPI document. You write server code to use each of the input parameters to accomplish whatever business purpose that operation is responsible for, possibly returning a result as a POJO or Java type as indicated for that operation in the OpenAPI document.
 // end::using-generated-code-server-intro[]
 
 In some cases, you might need more control over the response sent to the client. In that case, specify the additional property `returnResponse=true` when you run the Helidon server generator. The return type for the generated methods is

docs/src/main/asciidoc/mp/openapi/openapi-generator.adoc

@@ -24,8 +24,31 @@
 
 include::{rootdir}/includes/mp.adoc[]
 
-== Coming Soon
+:helidon-client-xref: {restclient-page}
 
-The support for link:{openapi-generator-tool-site-url}[OpenAPI generator] is not available yet.
+include::{rootdir}/includes/openapi/openapi-generator.adoc[tag=preamble]
 
-You can track the progress for this feature here: https://github.com/helidon-io/helidon/issues/7943.
+include::{rootdir}/includes/openapi/openapi-generator.adoc[tags=intro;coords;config;usage;using-generated-code-intro;using-generated-code-server;using-generated-code-client-intro]
+
+The Helidon MP client generator creates a MicroProfile REST client interface for each API.
+Each generated API interface is annotated so your code can `@Inject` the API into one of your own beans and then use the interface directly to invoke the remote service. Alternatively, you can also explicitly use the link:{microprofile-rest-client-javadoc-url}/org/eclipse/microprofile/rest/client/RestClientBuilder.html[`RestClientBuilder`] to create an instance programmatically and then invoke its methods to contact the remote service.
+The xref:{restclient-page}[Helidon MP REST Client] documentation describes both approaches in more detail.
+
+In the following example, `ExampleResource` (itself running in a server) invokes a remote Pet service and shows one way to use the generated `PetApi` REST client interface.
+
+
+[source,java]
+.Using the generated `PetApi` returned from a separate service
+----
+include::{sourcedir}/mp/openapi/OpenApiGeneratorSnippets.java[tag=class-declaration, indent=0]
+
+----
+<1> Uses a bean-defining annotation so CDI can inject into this class.
+<2> Requests that CDI inject the following field.
+<3> Identifies to Helidon MP that the following field is a REST client.
+<4> Declares the field using the generated `PetApi` type.
+<5> Invokes the remote service using the injected field and the parameter from the incoming request.
+
+
+include::{rootdir}/includes/openapi/openapi-generator.adoc[tag=common-references]
+* link:https://github.com/eclipse/microprofile-rest-client[MicroProfile REST Client specification]