Fix config doc annotations for OpenAPI builder

docs/shared/config/io.helidon.microprofile.openapi.MPOpenAPISupport.adoc

@@ -0,0 +1,59 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2022 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.
+
+///////////////////////////////////////////////////////////////////////////////
+
+:description: Configuration of io.helidon.microprofile.openapi.MPOpenAPISupport
+:keywords: helidon, config, io.helidon.microprofile.openapi.MPOpenAPISupport
+:basic-table-intro: The table below lists the configuration keys that configure io.helidon.microprofile.openapi.MPOpenAPISupport
+
+[source,text]
+.Type
+----
+io.helidon.microprofile.openapi.MPOpenAPISupport
+----
+
+
+
+==== Configuration options
+
+
+
+
+Optional configuration options:
+[cols="3,3,2,5"]
+
+|===
+|key |type |default value |description
+
+|`scan.exclude.classes` |string[] |{nbsp} |Specify the list of classes to exclude from scans.
+|`scan.classes` |string[] |{nbsp} |Specify the list of classes to scan.
+|`scan.disable` |boolean |`false` |Disable annotation scanning.
+|`scan.exclude.packages` |string[] |{nbsp} |Specify the list of packages to exclude from scans.
+|`scan.packages` |string[] |{nbsp} |Specify the list of packages to scan.
+|`web-context` |string |`/openapi` |Sets the web context path for the OpenAPI endpoint.
+|`cors` |link:../../shared/config/io.helidon.webserver.cors.CrossOriginConfig.adoc[CrossOriginConfig] |{nbsp} |Assigns the CORS settings for the OpenAPI endpoint.
+|`static-file` |string |`META-INF/openapi.(json|yaml|yml)` |Sets the file system path of the static OpenAPI document file.
+|`servers.operation.*` |string[] |{nbsp} |Sets alternative servers to service the indicated operation (represented here by '*'). Repeat for multiple operations.
+|`custom-schema-registry-class` |string |{nbsp} |Sets the custom schema registry class.
+|`schema.*` |string |{nbsp} |Sets the schema for the indicated fully-qualified class name (represented here by '*'); value is the schema in JSON format. Repeat for multiple classes. 
+|`application-path-disable` |boolean |`false` |Sets whether the app path search should be disabled.
+|`model.reader` |string |{nbsp} |Sets the developer-provided OpenAPI model reader class name.
+|`servers.path.{path}` |string[] |{nbsp} |Sets alternative servers to service all operations at the indicated path (represented here by '*'). Repeat for multiple paths.
+|`servers` |string[] |{nbsp} |Sets servers.
+|`filter` |string |{nbsp} |Sets the developer-provided OpenAPI filter class name.
+
+|===

docs/shared/config/io.helidon.openapi.SEOpenAPISupport.adoc

@@ -0,0 +1,54 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2022 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.
+
+///////////////////////////////////////////////////////////////////////////////
+
+:description: Configuration of io.helidon.openapi.SEOpenAPISupport
+:keywords: helidon, config, io.helidon.openapi.SEOpenAPISupport
+:basic-table-intro: The table below lists the configuration keys that configure io.helidon.openapi.SEOpenAPISupport
+
+[source,text]
+.Type
+----
+io.helidon.openapi.SEOpenAPISupport
+----
+
+
+
+==== Configuration options
+
+
+
+
+Optional configuration options:
+[cols="3,3,2,5"]
+
+|===
+|key |type |default value |description
+
+|`web-context` |string |`/openapi` |Sets the web context path for the OpenAPI endpoint.
+|`cors` |link:../../shared/config/io.helidon.webserver.cors.CrossOriginConfig.adoc[CrossOriginConfig] |{nbsp} |Assigns the CORS settings for the OpenAPI endpoint.
+|`static-file` |string |`META-INF/openapi.(json|yaml|yml)` |Sets the file system path of the static OpenAPI document file.
+|`custom-schema-registry-class` |string |{nbsp} |Sets the custom schema registry class.
+|`application-path-disable` |boolean |`false` |Sets whether the app path search should be disabled.
+|`model.reader` |string |{nbsp} |Sets the developer-provided OpenAPI model reader class name.
+|`servers.path.{path}` |string[] |{nbsp} |Sets alternative servers to service all operations in the specified path. Repeat for multiple paths.
+|`schema.{fully-qualified-class-name}` |string |{nbsp} |Sets the schema for the specified class; value is the schema in JSON format. Repeat for multiple classes. 
+|`servers.operation.{operationId}` |string[] |{nbsp} |Sets alternative servers to service the specified operation. Repeat for multiple operations.
+|`servers` |string[] |{nbsp} |Sets servers.
+|`filter` |string |{nbsp} |Sets the developer-provided OpenAPI filter class name.
+
+|===

microprofile/openapi/pom.xml

@@ -102,6 +102,18 @@
             <groupId>io.helidon.openapi</groupId>
             <artifactId>helidon-openapi</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.helidon.config</groupId>
+            <artifactId>helidon-config-metadata</artifactId>
+            <scope>provided</scope>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.config</groupId>
+            <artifactId>helidon-config-metadata-processor</artifactId>
+            <scope>provided</scope>
+            <optional>true</optional>
+        </dependency>
         <dependency>
             <groupId>jakarta.interceptor</groupId>
             <artifactId>jakarta.interceptor-api</artifactId>

microprofile/openapi/src/main/java/io/helidon/microprofile/openapi/MPOpenAPIBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, 2021 Oracle and/or its affiliates.
+ * Copyright (c) 2019, 2022 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.
@@ -27,9 +27,12 @@
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
+import io.helidon.config.metadata.Configured;
+import io.helidon.config.metadata.ConfiguredOption;
 import io.helidon.microprofile.server.JaxRsApplication;
 import io.helidon.microprofile.server.JaxRsCdiExtension;
 import io.helidon.openapi.OpenAPISupport;
+import io.helidon.openapi.SEOpenAPISupportBuilder;
 
 import io.smallrye.openapi.api.OpenApiConfig;
 import io.smallrye.openapi.api.OpenApiConfigImpl;
@@ -49,16 +52,23 @@
 /**
  * Fluent builder for OpenAPISupport in Helidon MP.
  */
+@Configured(prefix = MPOpenAPIBuilder.MP_OPENAPI_CONFIG_PREFIX)
 public final class MPOpenAPIBuilder extends OpenAPISupport.Builder<MPOpenAPIBuilder> {
 
-    private static final String USE_JAXRS_SEMANTICS_CONFIG_KEY = "mp.openapi.extensions.helidon.use-jaxrs-semantics";
+    // This is the prefix users will use in the config file.
+    static final String MP_OPENAPI_CONFIG_PREFIX = "mp." + SEOpenAPISupportBuilder.CONFIG_KEY;
+
+    private static final String USE_JAXRS_SEMANTICS_CONFIG_KEY = "use-jaxrs-semantics";
+
+    private static final String USE_JAXRS_SEMANTICS_FULL_CONFIG_KEY =
+            "mp.openapi.extensions.helidon." + USE_JAXRS_SEMANTICS_CONFIG_KEY;
     private static final boolean USE_JAXRS_SEMANTICS_DEFAULT = true;
 
     private static final Logger LOGGER = Logger.getLogger(MPOpenAPIBuilder.class.getName());
 
     private OpenApiConfig openAPIConfig;
 
-    private boolean useJaxRsSemantics = true;
+    private boolean useJaxRsSemantics = USE_JAXRS_SEMANTICS_DEFAULT;
 
     /*
      * Provided by the OpenAPI CDI extension for retrieving a single IndexView of all scanned types for the single-app or
@@ -242,7 +252,7 @@ private FilteredIndexView filteredIndexView(FilteredIndexView viewFilteredByConf
             if (LOGGER.isLoggable(Level.FINE)) {
                 LOGGER.log(Level.FINE, String.format(
                         "No filtering required for %s; although it returns a non-empty set from getSingletons, JAX-RS semantics "
-                                + "has been turned off for OpenAPI processing using " + USE_JAXRS_SEMANTICS_CONFIG_KEY,
+                                + "has been turned off for OpenAPI processing using " + USE_JAXRS_SEMANTICS_FULL_CONFIG_KEY,
                         appClassName));
             }
             return viewFilteredByConfig;
@@ -346,10 +356,40 @@ private MPOpenAPIBuilder openAPIConfig(OpenApiConfig config) {
         return this;
     }
 
-    MPOpenAPIBuilder config(Config mpConfig) {
+    /**
+     * Assigns various OpenAPI settings from the specified MP OpenAPI {@code Config} object.
+     *
+     * @param mpConfig the OpenAPI {@code Config} object possibly containing settings
+     * @return updated builder instance
+     */
+    @ConfiguredOption(type = OpenApiConfig.class, mergeWithParent = true)
+    @ConfiguredOption(key = "scan.disable",
+                      type = Boolean.class,
+                      value = "false",
+                      description = "Disable annotation scanning.")
+    @ConfiguredOption(key = "scan.packages",
+                      type = String.class,
+                      kind = ConfiguredOption.Kind.LIST,
+                      description = "Specify the list of packages to scan.")
+    @ConfiguredOption(key = "scan.classes",
+                      type = String.class,
+                      kind = ConfiguredOption.Kind.LIST,
+                      description = "Specify the list of classes to scan.")
+    @ConfiguredOption(key = "scan.exclude.packages",
+                      type = String.class,
+                      kind = ConfiguredOption.Kind.LIST,
+                      description = "Specify the list of packages to exclude from scans.")
+    @ConfiguredOption(key = "scan.exclude.classes",
+                      type = String.class,
+                      kind = ConfiguredOption.Kind.LIST,
+                      description = "Specify the list of classes to exclude from scans.")
+    public MPOpenAPIBuilder config(Config mpConfig) {
         this.mpConfig = mpConfig;
+
+        // use-jaxrs-semantics is intended for Helidon's private use in running the TCKs to work around a problem there.
+        // We do not document its use.
         useJaxRsSemantics = mpConfig
-                .getOptionalValue(USE_JAXRS_SEMANTICS_CONFIG_KEY, Boolean.class)
+                .getOptionalValue(USE_JAXRS_SEMANTICS_FULL_CONFIG_KEY, Boolean.class)
                 .orElse(USE_JAXRS_SEMANTICS_DEFAULT);
         return openAPIConfig(new OpenApiConfigImpl(mpConfig));
     }

microprofile/openapi/src/main/java/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, 2021 Oracle and/or its affiliates.
+ * Copyright (c) 2019, 2022 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.
@@ -33,6 +33,8 @@
 
     requires org.jboss.jandex;
 
+    requires static io.helidon.config.metadata;
+
     exports io.helidon.microprofile.openapi;
 
     // this is needed for CDI extensions that use non-public observer methods

openapi/pom.xml

@@ -150,6 +150,18 @@
             <groupId>jakarta.json</groupId>
             <artifactId>jakarta.json-api</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.helidon.config</groupId>
+            <artifactId>helidon-config-metadata</artifactId>
+            <scope>provided</scope>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.config</groupId>
+            <artifactId>helidon-config-metadata-processor</artifactId>
+            <scope>provided</scope>
+            <optional>true</optional>
+        </dependency>
         <dependency>
             <groupId>org.eclipse</groupId>
             <artifactId>yasson</artifactId>

openapi/src/main/java/io/helidon/openapi/OpenAPISupport.java

@@ -45,6 +45,8 @@
 import io.helidon.common.http.Http;
 import io.helidon.common.http.MediaType;
 import io.helidon.config.Config;
+import io.helidon.config.metadata.Configured;
+import io.helidon.config.metadata.ConfiguredOption;
 import io.helidon.media.common.MessageBodyReaderContext;
 import io.helidon.media.common.MessageBodyWriterContext;
 import io.helidon.media.jsonp.JsonpSupport;
@@ -593,6 +595,8 @@ enum OpenAPIMediaType {
 
         private static final OpenAPIMediaType DEFAULT_TYPE = YAML;
 
+        static final String TYPE_LIST = "json|yaml|yml"; // must be a true constant so it can be used in an annotation
+
         private final Format format;
         private final List<String> fileTypes;
         private final List<MediaType> mediaTypes;
@@ -607,7 +611,7 @@ private Format format() {
             return format;
         }
 
-        private List<String> matchingTypes() {
+        List<String> matchingTypes() {
             return fileTypes;
         }
 
@@ -716,6 +720,7 @@ static SEOpenAPISupportBuilder builderSE() {
      *
      * @param <B> concrete subclass of OpenAPISupport.Builder
      */
+    @Configured(description = "OpenAPI support configuration")
     public abstract static class Builder<B extends Builder<B>> implements io.helidon.common.Builder<B, OpenAPISupport> {
 
         /**
@@ -799,12 +804,13 @@ public void validate() throws IllegalStateException {
         }
 
         /**
-         * Path under which to register OpenAPI endpoint on the web server.
+         * Sets the web context path for the OpenAPI endpoint.
          *
          * @param path webContext to use, defaults to
          * {@value DEFAULT_WEB_CONTEXT}
          * @return updated builder instance
          */
+        @ConfiguredOption(DEFAULT_WEB_CONTEXT)
         public B webContext(String path) {
             if (!path.startsWith("/")) {
                 path = "/" + path;
@@ -814,23 +820,25 @@ public B webContext(String path) {
         }
 
         /**
-         * Sets the location of the static OpenAPI document file.
+         * Sets the file system path of the static OpenAPI document file.
          *
          * @param path non-null location of the static OpenAPI document file
          * @return updated builder instance
          */
+        @ConfiguredOption(DEFAULT_STATIC_FILE_PATH_PREFIX + "(" + OpenAPIMediaType.TYPE_LIST + ")")
         public B staticFile(String path) {
             Objects.requireNonNull(path, "path to static file must be non-null");
             staticFilePath = Optional.of(path);
             return identity();
         }
 
         /**
-         * Set the CORS config from the specified {@code CrossOriginConfig} object.
+         * Assigns the CORS settings for the OpenAPI endpoint.
          *
          * @param crossOriginConfig {@code CrossOriginConfig} containing CORS set-up
          * @return updated builder instance
          */
+        @ConfiguredOption(key = CORS_CONFIG_KEY)
         public B crossOriginConfig(CrossOriginConfig crossOriginConfig) {
             Objects.requireNonNull(crossOriginConfig, "CrossOriginConfig must be non-null");
             this.crossOriginConfig = crossOriginConfig;

openapi/src/main/java/io/helidon/openapi/SEOpenAPISupportBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, 2021 Oracle and/or its affiliates.
+ * Copyright (c) 2019, 2022 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.
@@ -18,6 +18,8 @@
 import java.util.Objects;
 
 import io.helidon.config.Config;
+import io.helidon.config.metadata.Configured;
+import io.helidon.config.metadata.ConfiguredOption;
 import io.helidon.openapi.internal.OpenAPIConfigImpl;
 
 import io.smallrye.openapi.api.OpenApiConfig;
@@ -30,12 +32,13 @@
  * {@link OpenApiConfig} which is what the smallrye implementation uses to
  * control its behavior.
  */
+@Configured(prefix = SEOpenAPISupportBuilder.CONFIG_KEY)
 public final class SEOpenAPISupportBuilder extends OpenAPISupport.Builder<SEOpenAPISupportBuilder> {
 
     private final OpenAPIConfigImpl.Builder apiConfigBuilder = OpenAPIConfigImpl.builder();
 
     /**
-     * Set various builder attributes from the specified openapi {@code Config} object.
+     * Assigns various OpenAPI settings from the specified openapi {@code Config} object.
      * <p>
      * The {@code Config} object can specify web-context and static-file in addition to settings
      * supported by {@link OpenAPIConfigImpl.Builder}.
@@ -44,6 +47,7 @@ public final class SEOpenAPISupportBuilder extends OpenAPISupport.Builder<SEOpen
      * @exception NullPointerException if the provided {@code Config} is null
      * @return updated builder instance
      */
+    @ConfiguredOption(type = OpenApiConfig.class, mergeWithParent = true)
     public SEOpenAPISupportBuilder config(Config config) {
         super.config(config);
         apiConfigBuilder.config(config);