Skip to content

Commit 7fefb4e

Browse files
tjquinnotjquinno
authored
Fix config doc annotations for OpenAPI builder (helidon-io#4419)
* Fix config doc annotations
1 parent 2bbcb32 commit 7fefb4e

11 files changed

Lines changed: 306 additions & 24 deletions

File tree

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

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
///////////////////////////////////////////////////////////////////////////////
2+
3+
Copyright (c) 2022 Oracle and/or its affiliates.
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
17+
///////////////////////////////////////////////////////////////////////////////
18+
19+
:description: Configuration of io.helidon.microprofile.openapi.MPOpenAPISupport
20+
:keywords: helidon, config, io.helidon.microprofile.openapi.MPOpenAPISupport
21+
:basic-table-intro: The table below lists the configuration keys that configure io.helidon.microprofile.openapi.MPOpenAPISupport
22+
23+
[source,text]
24+
.Type
25+
----
26+
io.helidon.microprofile.openapi.MPOpenAPISupport
27+
----
28+
29+
30+
31+
==== Configuration options
32+
33+
34+
35+
36+
Optional configuration options:
37+
[cols="3,3,2,5"]
38+
39+
|===
40+
|key |type |default value |description
41+
42+
|`scan.exclude.classes` |string[] |{nbsp} |Specify the list of classes to exclude from scans.
43+
|`scan.classes` |string[] |{nbsp} |Specify the list of classes to scan.
44+
|`scan.disable` |boolean |`false` |Disable annotation scanning.
45+
|`scan.exclude.packages` |string[] |{nbsp} |Specify the list of packages to exclude from scans.
46+
|`scan.packages` |string[] |{nbsp} |Specify the list of packages to scan.
47+
|`web-context` |string |`/openapi` |Sets the web context path for the OpenAPI endpoint.
48+
|`cors` |link:../../shared/config/io.helidon.webserver.cors.CrossOriginConfig.adoc[CrossOriginConfig] |{nbsp} |Assigns the CORS settings for the OpenAPI endpoint.
49+
|`static-file` |string |`META-INF/openapi.(json|yaml|yml)` |Sets the file system path of the static OpenAPI document file.
50+
|`servers.operation.*` |string[] |{nbsp} |Sets alternative servers to service the indicated operation (represented here by '*'). Repeat for multiple operations.
51+
|`custom-schema-registry-class` |string |{nbsp} |Sets the custom schema registry class.
52+
|`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.
53+
|`application-path-disable` |boolean |`false` |Sets whether the app path search should be disabled.
54+
|`model.reader` |string |{nbsp} |Sets the developer-provided OpenAPI model reader class name.
55+
|`servers.path.{path}` |string[] |{nbsp} |Sets alternative servers to service all operations at the indicated path (represented here by '*'). Repeat for multiple paths.
56+
|`servers` |string[] |{nbsp} |Sets servers.
57+
|`filter` |string |{nbsp} |Sets the developer-provided OpenAPI filter class name.
58+
59+
|===

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
///////////////////////////////////////////////////////////////////////////////
2+
3+
Copyright (c) 2022 Oracle and/or its affiliates.
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
17+
///////////////////////////////////////////////////////////////////////////////
18+
19+
:description: Configuration of io.helidon.openapi.SEOpenAPISupport
20+
:keywords: helidon, config, io.helidon.openapi.SEOpenAPISupport
21+
:basic-table-intro: The table below lists the configuration keys that configure io.helidon.openapi.SEOpenAPISupport
22+
23+
[source,text]
24+
.Type
25+
----
26+
io.helidon.openapi.SEOpenAPISupport
27+
----
28+
29+
30+
31+
==== Configuration options
32+
33+
34+
35+
36+
Optional configuration options:
37+
[cols="3,3,2,5"]
38+
39+
|===
40+
|key |type |default value |description
41+
42+
|`web-context` |string |`/openapi` |Sets the web context path for the OpenAPI endpoint.
43+
|`cors` |link:../../shared/config/io.helidon.webserver.cors.CrossOriginConfig.adoc[CrossOriginConfig] |{nbsp} |Assigns the CORS settings for the OpenAPI endpoint.
44+
|`static-file` |string |`META-INF/openapi.(json|yaml|yml)` |Sets the file system path of the static OpenAPI document file.
45+
|`custom-schema-registry-class` |string |{nbsp} |Sets the custom schema registry class.
46+
|`application-path-disable` |boolean |`false` |Sets whether the app path search should be disabled.
47+
|`model.reader` |string |{nbsp} |Sets the developer-provided OpenAPI model reader class name.
48+
|`servers.path.{path}` |string[] |{nbsp} |Sets alternative servers to service all operations in the specified path. Repeat for multiple paths.
49+
|`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.
50+
|`servers.operation.{operationId}` |string[] |{nbsp} |Sets alternative servers to service the specified operation. Repeat for multiple operations.
51+
|`servers` |string[] |{nbsp} |Sets servers.
52+
|`filter` |string |{nbsp} |Sets the developer-provided OpenAPI filter class name.
53+
54+
|===

‎microprofile/openapi/pom.xml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,18 @@
102102
<groupId>io.helidon.openapi</groupId>
103103
<artifactId>helidon-openapi</artifactId>
104104
</dependency>
105+
<dependency>
106+
<groupId>io.helidon.config</groupId>
107+
<artifactId>helidon-config-metadata</artifactId>
108+
<scope>provided</scope>
109+
<optional>true</optional>
110+
</dependency>
111+
<dependency>
112+
<groupId>io.helidon.config</groupId>
113+
<artifactId>helidon-config-metadata-processor</artifactId>
114+
<scope>provided</scope>
115+
<optional>true</optional>
116+
</dependency>
105117
<dependency>
106118
<groupId>jakarta.interceptor</groupId>
107119
<artifactId>jakarta.interceptor-api</artifactId>

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

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2019, 2021 Oracle and/or its affiliates.
2+
* Copyright (c) 2019, 2022 Oracle and/or its affiliates.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -27,9 +27,12 @@
2727
import java.util.regex.Pattern;
2828
import java.util.stream.Collectors;
2929

30+
import io.helidon.config.metadata.Configured;
31+
import io.helidon.config.metadata.ConfiguredOption;
3032
import io.helidon.microprofile.server.JaxRsApplication;
3133
import io.helidon.microprofile.server.JaxRsCdiExtension;
3234
import io.helidon.openapi.OpenAPISupport;
35+
import io.helidon.openapi.SEOpenAPISupportBuilder;
3336

3437
import io.smallrye.openapi.api.OpenApiConfig;
3538
import io.smallrye.openapi.api.OpenApiConfigImpl;
@@ -49,16 +52,23 @@
4952
/**
5053
* Fluent builder for OpenAPISupport in Helidon MP.
5154
*/
55+
@Configured(prefix = MPOpenAPIBuilder.MP_OPENAPI_CONFIG_PREFIX)
5256
public final class MPOpenAPIBuilder extends OpenAPISupport.Builder<MPOpenAPIBuilder> {
5357

54-
private static final String USE_JAXRS_SEMANTICS_CONFIG_KEY = "mp.openapi.extensions.helidon.use-jaxrs-semantics";
58+
// This is the prefix users will use in the config file.
59+
static final String MP_OPENAPI_CONFIG_PREFIX = "mp." + SEOpenAPISupportBuilder.CONFIG_KEY;
60+
61+
private static final String USE_JAXRS_SEMANTICS_CONFIG_KEY = "use-jaxrs-semantics";
62+
63+
private static final String USE_JAXRS_SEMANTICS_FULL_CONFIG_KEY =
64+
"mp.openapi.extensions.helidon." + USE_JAXRS_SEMANTICS_CONFIG_KEY;
5565
private static final boolean USE_JAXRS_SEMANTICS_DEFAULT = true;
5666

5767
private static final Logger LOGGER = Logger.getLogger(MPOpenAPIBuilder.class.getName());
5868

5969
private OpenApiConfig openAPIConfig;
6070

61-
private boolean useJaxRsSemantics = true;
71+
private boolean useJaxRsSemantics = USE_JAXRS_SEMANTICS_DEFAULT;
6272

6373
/*
6474
* 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
242252
if (LOGGER.isLoggable(Level.FINE)) {
243253
LOGGER.log(Level.FINE, String.format(
244254
"No filtering required for %s; although it returns a non-empty set from getSingletons, JAX-RS semantics "
245-
+ "has been turned off for OpenAPI processing using " + USE_JAXRS_SEMANTICS_CONFIG_KEY,
255+
+ "has been turned off for OpenAPI processing using " + USE_JAXRS_SEMANTICS_FULL_CONFIG_KEY,
246256
appClassName));
247257
}
248258
return viewFilteredByConfig;
@@ -346,10 +356,40 @@ private MPOpenAPIBuilder openAPIConfig(OpenApiConfig config) {
346356
return this;
347357
}
348358

349-
MPOpenAPIBuilder config(Config mpConfig) {
359+
/**
360+
* Assigns various OpenAPI settings from the specified MP OpenAPI {@code Config} object.
361+
*
362+
* @param mpConfig the OpenAPI {@code Config} object possibly containing settings
363+
* @return updated builder instance
364+
*/
365+
@ConfiguredOption(type = OpenApiConfig.class, mergeWithParent = true)
366+
@ConfiguredOption(key = "scan.disable",
367+
type = Boolean.class,
368+
value = "false",
369+
description = "Disable annotation scanning.")
370+
@ConfiguredOption(key = "scan.packages",
371+
type = String.class,
372+
kind = ConfiguredOption.Kind.LIST,
373+
description = "Specify the list of packages to scan.")
374+
@ConfiguredOption(key = "scan.classes",
375+
type = String.class,
376+
kind = ConfiguredOption.Kind.LIST,
377+
description = "Specify the list of classes to scan.")
378+
@ConfiguredOption(key = "scan.exclude.packages",
379+
type = String.class,
380+
kind = ConfiguredOption.Kind.LIST,
381+
description = "Specify the list of packages to exclude from scans.")
382+
@ConfiguredOption(key = "scan.exclude.classes",
383+
type = String.class,
384+
kind = ConfiguredOption.Kind.LIST,
385+
description = "Specify the list of classes to exclude from scans.")
386+
public MPOpenAPIBuilder config(Config mpConfig) {
350387
this.mpConfig = mpConfig;
388+
389+
// use-jaxrs-semantics is intended for Helidon's private use in running the TCKs to work around a problem there.
390+
// We do not document its use.
351391
useJaxRsSemantics = mpConfig
352-
.getOptionalValue(USE_JAXRS_SEMANTICS_CONFIG_KEY, Boolean.class)
392+
.getOptionalValue(USE_JAXRS_SEMANTICS_FULL_CONFIG_KEY, Boolean.class)
353393
.orElse(USE_JAXRS_SEMANTICS_DEFAULT);
354394
return openAPIConfig(new OpenApiConfigImpl(mpConfig));
355395
}

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2019, 2021 Oracle and/or its affiliates.
2+
* Copyright (c) 2019, 2022 Oracle and/or its affiliates.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -33,6 +33,8 @@
3333

3434
requires org.jboss.jandex;
3535

36+
requires static io.helidon.config.metadata;
37+
3638
exports io.helidon.microprofile.openapi;
3739

3840
// this is needed for CDI extensions that use non-public observer methods

‎openapi/pom.xml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,18 @@
150150
<groupId>jakarta.json</groupId>
151151
<artifactId>jakarta.json-api</artifactId>
152152
</dependency>
153+
<dependency>
154+
<groupId>io.helidon.config</groupId>
155+
<artifactId>helidon-config-metadata</artifactId>
156+
<scope>provided</scope>
157+
<optional>true</optional>
158+
</dependency>
159+
<dependency>
160+
<groupId>io.helidon.config</groupId>
161+
<artifactId>helidon-config-metadata-processor</artifactId>
162+
<scope>provided</scope>
163+
<optional>true</optional>
164+
</dependency>
153165
<dependency>
154166
<groupId>org.eclipse</groupId>
155167
<artifactId>yasson</artifactId>

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

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@
4545
import io.helidon.common.http.Http;
4646
import io.helidon.common.http.MediaType;
4747
import io.helidon.config.Config;
48+
import io.helidon.config.metadata.Configured;
49+
import io.helidon.config.metadata.ConfiguredOption;
4850
import io.helidon.media.common.MessageBodyReaderContext;
4951
import io.helidon.media.common.MessageBodyWriterContext;
5052
import io.helidon.media.jsonp.JsonpSupport;
@@ -593,6 +595,8 @@ enum OpenAPIMediaType {
593595

594596
private static final OpenAPIMediaType DEFAULT_TYPE = YAML;
595597

598+
static final String TYPE_LIST = "json|yaml|yml"; // must be a true constant so it can be used in an annotation
599+
596600
private final Format format;
597601
private final List<String> fileTypes;
598602
private final List<MediaType> mediaTypes;
@@ -607,7 +611,7 @@ private Format format() {
607611
return format;
608612
}
609613

610-
private List<String> matchingTypes() {
614+
List<String> matchingTypes() {
611615
return fileTypes;
612616
}
613617

@@ -716,6 +720,7 @@ static SEOpenAPISupportBuilder builderSE() {
716720
*
717721
* @param <B> concrete subclass of OpenAPISupport.Builder
718722
*/
723+
@Configured(description = "OpenAPI support configuration")
719724
public abstract static class Builder<B extends Builder<B>> implements io.helidon.common.Builder<B, OpenAPISupport> {
720725

721726
/**
@@ -799,12 +804,13 @@ public void validate() throws IllegalStateException {
799804
}
800805

801806
/**
802-
* Path under which to register OpenAPI endpoint on the web server.
807+
* Sets the web context path for the OpenAPI endpoint.
803808
*
804809
* @param path webContext to use, defaults to
805810
* {@value DEFAULT_WEB_CONTEXT}
806811
* @return updated builder instance
807812
*/
813+
@ConfiguredOption(DEFAULT_WEB_CONTEXT)
808814
public B webContext(String path) {
809815
if (!path.startsWith("/")) {
810816
path = "/" + path;
@@ -814,23 +820,25 @@ public B webContext(String path) {
814820
}
815821

816822
/**
817-
* Sets the location of the static OpenAPI document file.
823+
* Sets the file system path of the static OpenAPI document file.
818824
*
819825
* @param path non-null location of the static OpenAPI document file
820826
* @return updated builder instance
821827
*/
828+
@ConfiguredOption(DEFAULT_STATIC_FILE_PATH_PREFIX + "(" + OpenAPIMediaType.TYPE_LIST + ")")
822829
public B staticFile(String path) {
823830
Objects.requireNonNull(path, "path to static file must be non-null");
824831
staticFilePath = Optional.of(path);
825832
return identity();
826833
}
827834

828835
/**
829-
* Set the CORS config from the specified {@code CrossOriginConfig} object.
836+
* Assigns the CORS settings for the OpenAPI endpoint.
830837
*
831838
* @param crossOriginConfig {@code CrossOriginConfig} containing CORS set-up
832839
* @return updated builder instance
833840
*/
841+
@ConfiguredOption(key = CORS_CONFIG_KEY)
834842
public B crossOriginConfig(CrossOriginConfig crossOriginConfig) {
835843
Objects.requireNonNull(crossOriginConfig, "CrossOriginConfig must be non-null");
836844
this.crossOriginConfig = crossOriginConfig;

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

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2019, 2021 Oracle and/or its affiliates.
2+
* Copyright (c) 2019, 2022 Oracle and/or its affiliates.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -18,6 +18,8 @@
1818
import java.util.Objects;
1919

2020
import io.helidon.config.Config;
21+
import io.helidon.config.metadata.Configured;
22+
import io.helidon.config.metadata.ConfiguredOption;
2123
import io.helidon.openapi.internal.OpenAPIConfigImpl;
2224

2325
import io.smallrye.openapi.api.OpenApiConfig;
@@ -30,12 +32,13 @@
3032
* {@link OpenApiConfig} which is what the smallrye implementation uses to
3133
* control its behavior.
3234
*/
35+
@Configured(prefix = SEOpenAPISupportBuilder.CONFIG_KEY)
3336
public final class SEOpenAPISupportBuilder extends OpenAPISupport.Builder<SEOpenAPISupportBuilder> {
3437

3538
private final OpenAPIConfigImpl.Builder apiConfigBuilder = OpenAPIConfigImpl.builder();
3639

3740
/**
38-
* Set various builder attributes from the specified openapi {@code Config} object.
41+
* Assigns various OpenAPI settings from the specified openapi {@code Config} object.
3942
* <p>
4043
* The {@code Config} object can specify web-context and static-file in addition to settings
4144
* supported by {@link OpenAPIConfigImpl.Builder}.
@@ -44,6 +47,7 @@ public final class SEOpenAPISupportBuilder extends OpenAPISupport.Builder<SEOpen
4447
* @exception NullPointerException if the provided {@code Config} is null
4548
* @return updated builder instance
4649
*/
50+
@ConfiguredOption(type = OpenApiConfig.class, mergeWithParent = true)
4751
public SEOpenAPISupportBuilder config(Config config) {
4852
super.config(config);
4953
apiConfigBuilder.config(config);

0 commit comments

Comments
 (0)