added include-gavs option & docu

Michael Sonnleitner · Michael Sonnleitner · commit 05456ff82908 · 2025-11-10T11:59:39.000+01:00
diff --git a/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/CodegenConfig.java b/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/CodegenConfig.java
@@ -40,6 +40,7 @@ enum ConfigName {
         INCLUDE("include"),
         EXCLUDE("exclude"),
         ARTIFACT_ID_FILTER("artifact-id-filter"),
+        INCLUDE_GAVS("include-gavs"),
         EXCLUDE_GAVS("exclude-gavs"),
         VALIDATE_SPEC("validateSpec"),
         DEFAULT_SECURITY_SCHEME("default-security-scheme"),
diff --git a/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/GlobalCodegenConfig.java b/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/GlobalCodegenConfig.java
@@ -74,6 +74,20 @@ public interface GlobalCodegenConfig extends CommonItemConfig {
     @WithName("exclude-gavs")
     Optional<List<String>> excludeGavs();
 
+    /**
+     * Option to specify GAVs for which generation should be executed only.
+     *
+     * Depending on the GAV Provider default behavior differs:
+     * <ul>
+     * <li>for {@link io.quarkiverse.openapi.generator.deployment.codegen.YamlOrJsonGAVCoordinateOpenApiSpecInputProvider}, all
+     * suitable GAVs will be considered for generation if config value is not given</li>
+     * <li>for {@link io.quarkiverse.openapi.generator.deployment.codegen.JarOrZipGAVCoordinateOpenApiSpecInputProvider}, only
+     * specified GAVs will be considered for generation if config value is available</li>
+     * </ul>
+     */
+    @WithName("include-gavs")
+    Optional<List<String>> includeGavs();
+
     /**
      * Create security for the referenced security scheme
      */
diff --git a/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/AbstractGAVCoordinateOpenApiSpecInputProvider.java b/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/AbstractGAVCoordinateOpenApiSpecInputProvider.java
@@ -37,6 +37,7 @@ public List<SpecInputModel> read(CodeGenContext context) throws CodeGenException
                 .filter(rd -> getSupportedExtensions().contains(rd.getType().toLowerCase()))
                 .filter(rd -> rd.getArtifactId().matches(artifactIdFilter))
                 .filter(rd -> !gavsToExclude.contains(rd.getKey().toGacString()))
+                .filter(rd -> specificGAVSpecInputProviderFilter(context, rd.getKey().toGacString()))
                 .toList();
 
         if (dependencies.isEmpty()) {
@@ -57,8 +58,30 @@ public List<SpecInputModel> read(CodeGenContext context) throws CodeGenException
 
     protected abstract Set<String> getSupportedExtensions();
 
+    /**
+     * Adds input models to the provided list based on the given context, GAC string, and path.
+     * This method is implemented by subclasses to generate or retrieve the appropriate
+     * {@code SpecInputModel} instances that will be processed during code generation.
+     *
+     * @param context the code generation context, providing access to configuration and utilities
+     * @param gacString the GAC (Group, Artifact, Classifier) string representing the dependency identifier
+     * @param path the path to the file or directory containing the input specification(s)
+     * @param inputModels the list to which the generated {@code SpecInputModel} instances are added
+     * @throws CodeGenException if an error occurs while processing the input specifications
+     */
     protected abstract void addInputModels(CodeGenContext context,
             String gacString,
             Path path,
             List<SpecInputModel> inputModels) throws CodeGenException;
+
+    /**
+     * Filters dependencies based on specific criteria defined in the implementing class.
+     * This method is invoked as part of the dependency resolution process to determine
+     * whether a dependency identified by its GAC string should be included for further processing.
+     *
+     * @param context the code generation context, providing access to configuration and other utilities
+     * @param gacString the GAC (Group, Artifact, Classifier) string representing the dependency identifier
+     * @return true if the dependency matches the filter criteria and should be included; false otherwise
+     */
+    protected abstract boolean specificGAVSpecInputProviderFilter(CodeGenContext context, String gacString);
 }
diff --git a/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/JarOrZipGAVCoordinateOpenApiSpecInputProvider.java b/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/JarOrZipGAVCoordinateOpenApiSpecInputProvider.java
@@ -9,6 +9,7 @@
 import java.nio.file.Paths;
 import java.util.List;
 import java.util.Set;
+import java.util.stream.Collectors;
 
 import io.quarkus.bootstrap.prebuild.CodeGenException;
 import io.quarkus.deployment.CodeGenContext;
@@ -40,6 +41,7 @@
  * <li>Filters dependencies by artifact type (jar/zip)</li>
  * <li>Applies artifact ID filtering using a regex pattern</li>
  * <li>Excludes specific GAVs based on configuration</li>
+ * <li>Includes specific GAVs based on configuration if not available no GAVs are used</li>
  * <li>Creates {@link ZippedSpecInputModel} instances for each matching dependency and openAPI specification file</li>
  * </ol>
  *
@@ -95,7 +97,16 @@ protected void addInputModels(CodeGenContext context,
         }
     }
 
+    @Override
     protected Set<String> getSupportedExtensions() {
         return SUPPORTED_EXTENSIONS;
     }
+
+    @Override
+    protected boolean specificGAVSpecInputProviderFilter(final CodeGenContext context, final String gacString) {
+        return context.config().getOptionalValues(getGlobalConfigName(INCLUDE_GAVS), String.class)
+                .orElse(List.of()) // default to empty list to disable all if not specified
+                .stream().collect(Collectors.toSet())
+                .contains(gacString);
+    }
 }
diff --git a/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/YamlOrJsonGAVCoordinateOpenApiSpecInputProvider.java b/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/YamlOrJsonGAVCoordinateOpenApiSpecInputProvider.java
@@ -1,12 +1,15 @@
 package io.quarkiverse.openapi.generator.deployment.codegen;
 
+import static io.quarkiverse.openapi.generator.deployment.CodegenConfig.*;
+import static io.quarkiverse.openapi.generator.deployment.CodegenConfig.ConfigName.*;
 import static io.quarkiverse.openapi.generator.deployment.codegen.OpenApiGeneratorCodeGenBase.*;
 
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.List;
 import java.util.Set;
+import java.util.stream.Collectors;
 
 import io.quarkus.bootstrap.prebuild.CodeGenException;
 import io.quarkus.deployment.CodeGenContext;
@@ -29,6 +32,7 @@
  * <li>Filters dependencies by artifact type (yaml/yml/json)</li>
  * <li>Applies artifact ID filtering using a regex pattern</li>
  * <li>Excludes specific GAVs based on configuration</li>
+ * <li>Includes specific GAVs based on configuration if available otherwise all GAVs are used</li>
  * <li>Creates {@link SpecInputModel} instances for each matching dependency</li>
  * </ol>
  *
@@ -74,4 +78,16 @@ protected void addInputModels(CodeGenContext context,
     protected Set<String> getSupportedExtensions() {
         return SUPPORTED_EXTENSIONS;
     }
+
+    @Override
+    protected boolean specificGAVSpecInputProviderFilter(final CodeGenContext context, final String gacString) {
+        List<String> includeGavs = context.config().getOptionalValues(getGlobalConfigName(INCLUDE_GAVS), String.class)
+                .orElse(null);
+        if (includeGavs == null) { // default behavior: all GAVs are included
+            return true;
+        }
+        return includeGavs
+                .stream().collect(Collectors.toSet())
+                .contains(gacString);
+    }
 }
diff --git a/client/integration-tests/gav/src/it/02-consume-gav/pom.xml b/client/integration-tests/gav/src/it/02-consume-gav/pom.xml
@@ -59,7 +59,7 @@
             <type>yaml</type>
         </dependency>
 
-        <!-- GAV YAML dependencies -->
+        <!-- GAV JAR dependencies -->
         <dependency>
             <groupId>io.quarkiverse.openapi.generator</groupId>
             <artifactId>quarkus-openapi-generator-gav-source-splitted-echo</artifactId>
diff --git a/client/integration-tests/gav/src/it/02-consume-gav/src/main/resources/application.properties b/client/integration-tests/gav/src/it/02-consume-gav/src/main/resources/application.properties
@@ -2,6 +2,9 @@ quarkus.keycloak.devservices.enabled=false
 
 quarkus.openapi-generator.codegen.artifact-id-filter=.*echo.*
 quarkus.openapi-generator.codegen.exclude-gavs=io.quarkiverse.openapi.generator:quarkus-openapi-generator-gav-source-echo2
+quarkus.openapi-generator.codegen.include-gavs=io.quarkiverse.openapi.generator:quarkus-openapi-generator-gav-source-echo1,\
+    io.quarkiverse.openapi.generator:quarkus-openapi-generator-gav-source-selfcontained-echo,\
+    io.quarkiverse.openapi.generator:quarkus-openapi-generator-gav-source-splitted-echo
 quarkus.openapi-generator.codegen.spec.io_quarkiverse_openapi_generator_quarkus_openapi_generator_gav_source_echo1.serializable-model=true
 
 quarkus.openapi-generator.codegen.spec.io_quarkiverse_openapi_generator_quarkus_openapi_generator_gav_source_splitted_echo.gav-spec-files=echo.yaml
diff --git a/docs/modules/ROOT/pages/includes/quarkus-openapi-generator.adoc b/docs/modules/ROOT/pages/includes/quarkus-openapi-generator.adoc
@@ -685,6 +685,30 @@ endif::add-copy-button-to-env-var[]
 |list of string
 |
 
+a|icon:lock[title=Fixed at build time] [[quarkus-openapi-generator_quarkus-openapi-generator-codegen-include-gavs]] [.property-path]##link:#quarkus-openapi-generator_quarkus-openapi-generator-codegen-include-gavs[`quarkus.openapi-generator.codegen.include-gavs`]##
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.openapi-generator.codegen.include-gavs+++[]
+endif::add-copy-button-to-config-props[]
+
+
+[.description]
+--
+Option to specify GAVs for which generation should be executed only. Depending on the GAV Provider default behavior differs:
+
+ - for `io.quarkiverse.openapi.generator.deployment.codegen.YamlOrJsonGAVCoordinateOpenApiSpecInputProvider`, all suitable GAVs will be considered for generation if config value is not given
+ - for `io.quarkiverse.openapi.generator.deployment.codegen.JarOrZipGAVCoordinateOpenApiSpecInputProvider`, only specified GAVs will be considered for generation if config value is available
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_INCLUDE_GAVS+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_INCLUDE_GAVS+++`
+endif::add-copy-button-to-env-var[]
+--
+|list of string
+|
+
 a|icon:lock[title=Fixed at build time] [[quarkus-openapi-generator_quarkus-openapi-generator-codegen-default-security-scheme]] [.property-path]##link:#quarkus-openapi-generator_quarkus-openapi-generator-codegen-default-security-scheme[`quarkus.openapi-generator.codegen.default-security-scheme`]##
 ifdef::add-copy-button-to-config-props[]
 config_property_copy_button:+++quarkus.openapi-generator.codegen.default-security-scheme+++[]
@@ -1405,6 +1429,27 @@ endif::add-copy-button-to-env-var[]
 |boolean
 |`+++false+++`
 
+a|icon:lock[title=Fixed at build time] [[quarkus-openapi-generator_quarkus-openapi-generator-codegen-spec-spec-item-gav-spec-files]] [.property-path]##link:#quarkus-openapi-generator_quarkus-openapi-generator-codegen-spec-spec-item-gav-spec-files[`quarkus.openapi-generator.codegen.spec."spec-item".gav-spec-files`]##
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.openapi-generator.codegen.spec."spec-item".gav-spec-files+++[]
+endif::add-copy-button-to-config-props[]
+
+
+[.description]
+--
+List of OpenAPI spec files in GAV to be generated
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_SPEC__SPEC_ITEM__GAV_SPEC_FILES+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_SPEC__SPEC_ITEM__GAV_SPEC_FILES+++`
+endif::add-copy-button-to-env-var[]
+--
+|list of string
+|`+++openapi.yaml+++`
+
 a| [[quarkus-openapi-generator_quarkus-openapi-generator-item-configs-auth-auth-configs-token-propagation]] [.property-path]##link:#quarkus-openapi-generator_quarkus-openapi-generator-item-configs-auth-auth-configs-token-propagation[`quarkus.openapi-generator."item-configs".auth."auth-configs".token-propagation`]##
 ifdef::add-copy-button-to-config-props[]
 config_property_copy_button:+++quarkus.openapi-generator."item-configs".auth."auth-configs".token-propagation+++[]
diff --git a/docs/modules/ROOT/pages/includes/quarkus-openapi-generator_quarkus.openapi-generator.adoc b/docs/modules/ROOT/pages/includes/quarkus-openapi-generator_quarkus.openapi-generator.adoc
@@ -685,6 +685,30 @@ endif::add-copy-button-to-env-var[]
 |list of string
 |
 
+a|icon:lock[title=Fixed at build time] [[quarkus-openapi-generator_quarkus-openapi-generator-codegen-include-gavs]] [.property-path]##link:#quarkus-openapi-generator_quarkus-openapi-generator-codegen-include-gavs[`quarkus.openapi-generator.codegen.include-gavs`]##
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.openapi-generator.codegen.include-gavs+++[]
+endif::add-copy-button-to-config-props[]
+
+
+[.description]
+--
+Option to specify GAVs for which generation should be executed only. Depending on the GAV Provider default behavior differs:
+
+ - for `io.quarkiverse.openapi.generator.deployment.codegen.YamlOrJsonGAVCoordinateOpenApiSpecInputProvider`, all suitable GAVs will be considered for generation if config value is not given
+ - for `io.quarkiverse.openapi.generator.deployment.codegen.JarOrZipGAVCoordinateOpenApiSpecInputProvider`, only specified GAVs will be considered for generation if config value is available
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_INCLUDE_GAVS+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_INCLUDE_GAVS+++`
+endif::add-copy-button-to-env-var[]
+--
+|list of string
+|
+
 a|icon:lock[title=Fixed at build time] [[quarkus-openapi-generator_quarkus-openapi-generator-codegen-default-security-scheme]] [.property-path]##link:#quarkus-openapi-generator_quarkus-openapi-generator-codegen-default-security-scheme[`quarkus.openapi-generator.codegen.default-security-scheme`]##
 ifdef::add-copy-button-to-config-props[]
 config_property_copy_button:+++quarkus.openapi-generator.codegen.default-security-scheme+++[]
@@ -1405,6 +1429,27 @@ endif::add-copy-button-to-env-var[]
 |boolean
 |`+++false+++`
 
+a|icon:lock[title=Fixed at build time] [[quarkus-openapi-generator_quarkus-openapi-generator-codegen-spec-spec-item-gav-spec-files]] [.property-path]##link:#quarkus-openapi-generator_quarkus-openapi-generator-codegen-spec-spec-item-gav-spec-files[`quarkus.openapi-generator.codegen.spec."spec-item".gav-spec-files`]##
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.openapi-generator.codegen.spec."spec-item".gav-spec-files+++[]
+endif::add-copy-button-to-config-props[]
+
+
+[.description]
+--
+List of OpenAPI spec files in GAV to be generated
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_SPEC__SPEC_ITEM__GAV_SPEC_FILES+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_SPEC__SPEC_ITEM__GAV_SPEC_FILES+++`
+endif::add-copy-button-to-env-var[]
+--
+|list of string
+|`+++openapi.yaml+++`
+
 a| [[quarkus-openapi-generator_quarkus-openapi-generator-item-configs-auth-auth-configs-token-propagation]] [.property-path]##link:#quarkus-openapi-generator_quarkus-openapi-generator-item-configs-auth-auth-configs-token-propagation[`quarkus.openapi-generator."item-configs".auth."auth-configs".token-propagation`]##
 ifdef::add-copy-button-to-config-props[]
 config_property_copy_button:+++quarkus.openapi-generator."item-configs".auth."auth-configs".token-propagation+++[]

Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,7 @@`
`9`	`9`	`import java.nio.file.Paths;`
`10`	`10`	`import java.util.List;`
`11`	`11`	`import java.util.Set;`
	`12`	`+import java.util.stream.Collectors;`
`12`	`13`
`13`	`14`	`import io.quarkus.bootstrap.prebuild.CodeGenException;`
`14`	`15`	`import io.quarkus.deployment.CodeGenContext;`
`@@ -40,6 +41,7 @@`
`40`	`41`	`* <li>Filters dependencies by artifact type (jar/zip)</li>`
`41`	`42`	`* <li>Applies artifact ID filtering using a regex pattern</li>`
`42`	`43`	`* <li>Excludes specific GAVs based on configuration</li>`
	`44`	`+ * <li>Includes specific GAVs based on configuration if not available no GAVs are used</li>`
`43`	`45`	`* <li>Creates {@link ZippedSpecInputModel} instances for each matching dependency and openAPI specification file</li>`
`44`	`46`	`* </ol>`
`45`	`47`	`*`
`@@ -95,7 +97,16 @@ protected void addInputModels(CodeGenContext context,`
`95`	`97`	`}`
`96`	`98`	`}`
`97`	`99`
	`100`	`+ @Override`
`98`	`101`	`protected Set<String> getSupportedExtensions() {`
`99`	`102`	`return SUPPORTED_EXTENSIONS;`
`100`	`103`	`}`
	`104`	`+`
	`105`	`+ @Override`
	`106`	`+ protected boolean specificGAVSpecInputProviderFilter(final CodeGenContext context, final String gacString) {`
	`107`	`+ return context.config().getOptionalValues(getGlobalConfigName(INCLUDE_GAVS), String.class)`
	`108`	`+ .orElse(List.of()) // default to empty list to disable all if not specified`
	`109`	`+ .stream().collect(Collectors.toSet())`
	`110`	`+ .contains(gacString);`
	`111`	`+ }`
`101`	`112`	`}`