Doc update for the new Helidon 4 MP support in the Helidon OpenAPI code generators

docs/pom.xml

@@ -34,6 +34,7 @@
         <helidon.sitegen.skip>false</helidon.sitegen.skip>
         <version.lib.jbatch-api>2.1.0</version.lib.jbatch-api>
         <version.lib.jbatch.container>2.1.0</version.lib.jbatch.container>
+        <version.plugin.openapi-generator>7.6.0</version.plugin.openapi-generator>
     </properties>
 
     <dependencies>
@@ -87,8 +88,19 @@
         </dependencies>
     </dependencyManagement>
 
+
+
     <build>
         <finalName>${project.artifactId}</finalName>
+        <pluginManagement>
+            <plugins>
+                <plugin>
+                    <groupId>org.openapitools</groupId>
+                    <artifactId>openapi-generator-maven-plugin</artifactId>
+                    <version>${version.plugin.openapi-generator}</version>
+                </plugin>
+            </plugins>
+        </pluginManagement>
         <plugins>
             <plugin>
                 <groupId>io.helidon.build-tools</groupId>
@@ -101,6 +113,52 @@
                     <siteArchiveSkip>${helidon.sitegen.skip}</siteArchiveSkip>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>build-helper-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>compute-major-version</id>
+                        <goals>
+                            <goal>parse-version</goal>
+                        </goals>
+                        <phase>validate</phase>
+                        <configuration>
+                            <propertyPrefix>parsedHelidonVersion</propertyPrefix>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.openapitools</groupId>
+                <artifactId>openapi-generator-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>create-openapi-generator-project</id>
+                        <goals>
+                            <goal>generate</goal>
+                        </goals>
+                        <phase>generate-sources</phase>
+                        <configuration>
+                            <generatorName>java-helidon-client</generatorName>
+                            <library>mp</library>
+                            <inputSpec>${project.basedir}/src/main/resources/petstorex.yaml</inputSpec>
+                            <additionalProperties>
+                                <additionalProperty>helidonVersion=${parsedHelidonVersion.majorVersion}</additionalProperty>
+                            </additionalProperties>
+                            <output>${project.build.directory}/generated-sources/mp/client</output>
+                            <addCompileSourceRoot>true</addCompileSourceRoot>
+                            <configOptions>
+                                <groupId>io.helidon.docs.openapi.gen.mp</groupId>
+                                <artifactId>helidon-docs-openapi-gen-mp-client</artifactId>
+                                <apiPackage>io.helidon.docs.openapi.gen.mp.client.api</apiPackage>
+                                <modelPackage>io.helidon.docs.openapi.gen.model</modelPackage>
+                                <invokerPackage>io.helidon.docs.openapi.gen.mp.client</invokerPackage>
+                            </configOptions>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>

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

@@ -279,7 +279,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

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

@@ -24,8 +24,33 @@
 
 include::{rootdir}/includes/mp.adoc[]
 
-== Coming Soon
+:incdir: {rootdir}/includes/openapi
+:gen-inc: {incdir}/openapi-generator.adoc
+:helidon-client-xref: {restclient-page}
 
-The support for link:{openapi-generator-tool-site-url}[OpenAPI generator] is not available yet.
+include::{gen-inc}[tag=preamble]
 
-You can track the progress for this feature here: https://github.com/helidon-io/helidon/issues/7943.
+include::{gen-inc}[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/ExampleOpenApiGenClientResource.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::{gen-inc}[tag=common-references]
+* link:https://github.com/eclipse/microprofile-rest-client[MicroProfile REST Client specification]

docs/src/main/java/io/helidon/docs/mp/openapi/ExampleOpenApiGenClientResource.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2024 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.helidon.docs.mp.openapi;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.helidon.docs.openapi.gen.model.Pet;
+import io.helidon.docs.openapi.gen.mp.client.api.ApiException;
+import io.helidon.docs.openapi.gen.mp.client.api.PetApi;
+
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+
+
+// tag::class-declaration[]
+@Path("/exampleServiceCallingService") // <1>
+public class ExampleOpenApiGenClientResource {
+    @Inject // <2>
+    @RestClient // <3>
+    private PetApi petApi; // <4>
+
+    @GET
+    @Path("/getPet/{petId}")
+    @Produces(MediaType.APPLICATION_JSON)
+    public Pet getPetUsingId(@PathParam("petId") Long petId) throws ApiException {
+        Pet pet = petApi.getPetById(petId); // <5>
+        return pet;
+    }
+}
+// end::class-declaration[]