Merge branch 'dev-4.x' into my-dev-4.x

examples/microprofile/openapi/basic/README.md

@@ -0,0 +1,33 @@
+# Helidon MP OpenAPI Example
+
+This example shows a simple greeting application, similar to the one from the 
+Helidon MP QuickStart, enhanced with OpenAPI support.
+
+## Build and run
+
+```shell
+mvn package
+java -jar target/helidon-examples-microprofile-openapi-basic.jar
+```
+
+Try the endpoints:
+
+```shell
+curl -X GET http://localhost:8080/greet
+#Output: {"message":"Hello World!"}
+
+curl -X GET http://localhost:8080/greet/Joe
+#Output: {"message":"Hello Joe!"}
+
+curl -X PUT -H "Content-Type: application/json" -d '{"message" : "Hola"}' http://localhost:8080/greet/greeting
+
+curl -X GET http://localhost:8080/greet/Jose
+#Output: {"message":"Hola Jose!"}
+
+curl -X GET http://localhost:8080/openapi
+#Output: [lengthy OpenAPI document]
+```
+The output describes not only then endpoints from `GreetResource` but
+also one contributed by the `SimpleAPIModelReader`.
+
+

examples/microprofile/openapi/basic/pom.xml

@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2019, 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.
+
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.helidon.applications</groupId>
+        <artifactId>helidon-mp</artifactId>
+        <version>4.2.0-SNAPSHOT</version>
+        <relativePath/>
+    </parent>
+    <groupId>io.helidon.examples.microprofile</groupId>
+    <artifactId>helidon-examples-microprofile-openapi-basic</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <name>Helidon Examples Microprofile OpenAPI Basic</name>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.helidon.microprofile.bundles</groupId>
+            <artifactId>helidon-microprofile-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.microprofile.openapi</groupId>
+            <artifactId>helidon-microprofile-openapi</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.logging</groupId>
+            <artifactId>helidon-logging-jul</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.glassfish.jersey.media</groupId>
+            <artifactId>jersey-media-json-binding</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.smallrye</groupId>
+            <artifactId>jandex</artifactId>
+            <scope>runtime</scope>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.hamcrest</groupId>
+            <artifactId>hamcrest-all</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.microprofile.testing</groupId>
+            <artifactId>helidon-microprofile-testing-junit5</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-libs</id>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>io.smallrye</groupId>
+                <artifactId>jandex-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>make-index</id>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

examples/microprofile/openapi/src/main/java/io/helidon/microprofile/examples/openapi/GreetResource.java → examples/microprofile/openapi/basic/src/main/java/io/helidon/microprofile/examples/openapi/basic/GreetResource.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package io.helidon.microprofile.examples.openapi;
+package io.helidon.microprofile.examples.openapi.basic;
 
 import jakarta.enterprise.context.RequestScoped;
 import jakarta.inject.Inject;
@@ -50,7 +50,7 @@
  *
  * Note that the output will include not only the annotated endpoints from this
  * class but also an endpoint added by the
- * {@link io.helidon.microprofile.examples.openapi.internal.SimpleAPIModelReader}.
+ * {@link io.helidon.microprofile.examples.openapi.basic.internal.SimpleAPIModelReader}.
  *
  * The message is returned as a JSON object.
  */

examples/microprofile/openapi/src/main/java/io/helidon/microprofile/examples/openapi/GreetingMessage.java → examples/microprofile/openapi/basic/src/main/java/io/helidon/microprofile/examples/openapi/basic/GreetingMessage.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.helidon.microprofile.examples.openapi;
+package io.helidon.microprofile.examples.openapi.basic;
 
 /**
  * POJO defining the greeting message content.

examples/microprofile/openapi/src/main/java/io/helidon/microprofile/examples/openapi/GreetingProvider.java → examples/microprofile/openapi/basic/src/main/java/io/helidon/microprofile/examples/openapi/basic/GreetingProvider.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.helidon.microprofile.examples.openapi;
+package io.helidon.microprofile.examples.openapi.basic;
 
 import java.util.concurrent.atomic.AtomicReference;
 

examples/microprofile/openapi/src/main/java/io/helidon/microprofile/examples/openapi/internal/SimpleAPIFilter.java → examples/microprofile/openapi/basic/src/main/java/io/helidon/microprofile/examples/openapi/basic/internal/SimpleAPIFilter.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.helidon.microprofile.examples.openapi.internal;
+package io.helidon.microprofile.examples.openapi.basic.internal;
 
 import java.util.Map;
 

examples/microprofile/openapi/src/main/java/io/helidon/microprofile/examples/openapi/internal/SimpleAPIModelReader.java → examples/microprofile/openapi/basic/src/main/java/io/helidon/microprofile/examples/openapi/basic/internal/SimpleAPIModelReader.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.helidon.microprofile.examples.openapi.internal;
+package io.helidon.microprofile.examples.openapi.basic.internal;
 
 import org.eclipse.microprofile.openapi.OASFactory;
 import org.eclipse.microprofile.openapi.OASModelReader;

examples/microprofile/openapi/src/main/java/io/helidon/microprofile/examples/openapi/internal/package-info.java → examples/microprofile/openapi/basic/src/main/java/io/helidon/microprofile/examples/openapi/basic/internal/package-info.java

@@ -17,4 +17,4 @@
 /**
  * Internal classes supporting Helidon MP OpenAPI.
  */
-package io.helidon.microprofile.examples.openapi.internal;
+package io.helidon.microprofile.examples.openapi.basic.internal;

examples/microprofile/openapi/src/main/java/io/helidon/microprofile/examples/openapi/package-info.java → examples/microprofile/openapi/basic/src/main/java/io/helidon/microprofile/examples/openapi/basic/package-info.java

@@ -17,4 +17,4 @@
 /**
  * Helidon MicroProfile OpenAPI example.
  */
-package io.helidon.microprofile.examples.openapi;
+package io.helidon.microprofile.examples.openapi.basic;

examples/microprofile/openapi/src/main/resources/META-INF/microprofile-config.properties → examples/microprofile/openapi/basic/src/main/resources/META-INF/microprofile-config.properties

@@ -21,5 +21,5 @@ app.greeting=Hello
 server.port=8080
 server.host=0.0.0.0
 
-mp.openapi.filter=io.helidon.microprofile.examples.openapi.internal.SimpleAPIFilter
-mp.openapi.model.reader=io.helidon.microprofile.examples.openapi.internal.SimpleAPIModelReader
+mp.openapi.filter=io.helidon.microprofile.examples.openapi.basic.internal.SimpleAPIFilter
+mp.openapi.model.reader=io.helidon.microprofile.examples.openapi.basic.internal.SimpleAPIModelReader

examples/microprofile/openapi/src/test/java/io/helidon/microprofile/examples/openapi/MainTest.java → examples/microprofile/openapi/basic/src/test/java/io/helidon/microprofile/examples/openapi/basic/MainTest.java

@@ -14,9 +14,9 @@
  * limitations under the License.
  */
 
-package io.helidon.microprofile.examples.openapi;
+package io.helidon.microprofile.examples.openapi.basic;
 
-import io.helidon.microprofile.examples.openapi.internal.SimpleAPIModelReader;
+import io.helidon.microprofile.examples.openapi.basic.internal.SimpleAPIModelReader;
 import io.helidon.microprofile.testing.junit5.HelidonTest;
 
 import jakarta.inject.Inject;

examples/microprofile/openapi/expanded-jandex/README.md

@@ -0,0 +1,74 @@
+# Helidon MP OpenAPI Expanded Jandex Indexing Example
+
+This example shows a simple greeting application, similar to the basic OpenAPI MP example, but with proper handling of types from _outside_ this project that are used in resource method signatures.
+
+### Why might I need expanded Jandex handling?
+Many Helidon MP applications, including those created by the Helidon command line and the starter, run the Jandex plug-in to create an index file for the types defined in the project. 
+Helidon's OpenAPI support leverages much of SmallRye's OpenAPI implementation and SmallRye scans the resource methods in the application to generate an OpenAPI model. This scan uses the Jandex index file directly to get information about the types used in resource methods, and SmallRye uses this information in preparing the OpenAPI document.
+
+If a resource method's signature uses a type _outside_ the current project SmallRye's scan cannot usually find the type information because the Jandex index created by the typical project describes only the types defined in the current project, not types in any dependencies. 
+
+### How does this affect my application?
+In such cases, SmallRye logs warning messages about the types it cannot find. This can clutter the application output.
+
+More importantly, the resulting OpenAPI model is less robust. When SmallRye cannot find a type it has no choice but to model that type as an opaque `Object`. The resulting OpenAPI model and document are less useful than they could be. 
+
+Note that if the dependency contains _its own_ Jandex index for its own types then SmallRye can find information about those types.
+
+### What does this example do?
+This example shows how to expand the Jandex index built by your project to include selected types from _outside_ the project.
+There are two key differences from the basic OpenAPI example:
+
+1. The new resource method `mediaType`added to `GreetingResource` returns a `MediaType` from Jarkarta RESTful Web Wervices, a type from outside this project.
+2. The `pom.xml` configures its invocation of the Jandex plug-in to include that type in the generated Jandex index.
+
+The example `pom.xml` adds a single type from a single dependency to the index. If you need to for your application add more dependencies and more include entries. 
+
+## Build and run
+
+```shell
+mvn package
+java -jar target/helidon-examples-microprofile-openapi-expanded-jandex.jar
+```
+
+Try the endpoints. These are the same actions supported by the basic OpenAPI example:
+
+```shell
+curl -X GET http://localhost:8080/greet
+#Output: {"message":"Hello World!"}
+
+curl -X GET http://localhost:8080/greet/Joe
+#Output: {"message":"Hello Joe!"}
+
+curl -X PUT -H "Content-Type: application/json" -d '{"message" : "Hola"}' http://localhost:8080/greet/greeting
+
+curl -X GET http://localhost:8080/greet/Jose
+#Output: {"message":"Hola Jose!"}
+
+curl -X GET http://localhost:8080/openapi
+#Output: [lengthy OpenAPI document]
+```
+After running the last command notice that the OpenAPI document's `components/schemas` section contains a declaration for `MediaType` that includes the `MediaType` properties (`type`, `subtype`, etc.). Further, the document's entry for `paths/greet/mediatype:get` declares the response content by referring to that exact `#/components/schemas/MediaType` entry.
+
+## Building and running without expanded Jandex processing
+You can simulate the build without the expanded Jandex processing to see the warning SmallRye logs during startup and to see the difference in the generated OpenAPI document.
+When you build the project specify the `normal-jandex` Maven profile and skip the unit tests.
+
+```shell
+mvn clean package -Pnormal-jandex -DskipTests
+java -jar target/helidon-examples-microprofile-openapi-expanded-jandex.jar
+```
+As the app starts notice a message like the following in the app output:
+```list
+WARN io.smallrye.openapi.runtime.scanner Thread[#1,main,5,main]: SROAP04005: Could not find schema class in index: jakarta.ws.rs.core.MediaType
+```
+
+Retrieve the OpenAPI document:
+```shell
+curl -X GET http://localhost:8080/openapi
+```
+Notice two things about the output:
+1. The `components/schemas` section contains no entry for `MediaType`. That's expected given that SmallRye could not find the type information for it.
+2. The response content for `paths/greet/mediatype:get` is simply `object`.
+
+   While it is true that the response is an `Object` this version of the OpenAPI document for your app is less useful than the earlier one because of the missing type information for `MediaType`.