Fix #1065 - Add Dynamic URL support (#1094) (#1096)

github-actions[bot] · ricardozanini · web-flow · commit 2fb9384919da · 2025-04-08T12:34:15.000-04:00
* Add @url annotation by default on every api.qute generated methods * Fix #1065 - Add Dynamic URL support * Remove debug leftovers --------- Signed-off-by: Ricardo Zanini <ricardozanini@gmail.com> Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com>
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
@@ -77,7 +77,8 @@ enum ConfigName {
         GENERATE_MODELS("generate-models"),
         BEAN_VALIDATION("use-bean-validation"),
         SERIALIZABLE_MODEL("serializable-model"),
-        EQUALS_HASHCODE("equals-hashcode");
+        EQUALS_HASHCODE("equals-hashcode"),
+        USE_DYNAMIC_URL("use-dynamic-url");
 
         private final String name;
 
diff --git a/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/SpecItemConfig.java b/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/SpecItemConfig.java
@@ -2,6 +2,7 @@
 
 import java.util.Optional;
 
+import io.smallrye.config.WithDefault;
 import io.smallrye.config.WithName;
 
 /*
@@ -68,4 +69,14 @@ public interface SpecItemConfig extends CommonItemConfig {
     @WithName("serializable-model")
     Optional<Boolean> serializableModel();
 
+    /**
+     * Whether to enable Dynamic URLs on APIs methods.
+     * By enabling this property every method on `RestClients` will be annotated with `io.quarkus.rest.client.reactive.Url`.
+     *
+     * @see <a href="https://quarkus.io/version/3.20/guides/rest-client#dynamic-base-urls">Dynamic base URLs</a>
+     */
+    @WithName("use-dynamic-url")
+    @WithDefault("false")
+    Optional<Boolean> useDynamicUrl();
+
 }
diff --git a/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/OpenApiGeneratorCodeGenBase.java b/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/codegen/OpenApiGeneratorCodeGenBase.java
@@ -339,6 +339,9 @@ protected void generate(OpenApiGeneratorOptions options) {
                 OpenApiClientGeneratorWrapper.SUPPORTS_ADDITIONAL_PROPERTIES_AS_ATTRIBUTE,
                 additionalPropertiesAsAttribute.toString());
 
+        getValues(smallRyeConfig, openApiFilePath, CodegenConfig.ConfigName.USE_DYNAMIC_URL, Boolean.class)
+                .ifPresent(generator::withUseDynamicUrl);
+
         generator.generate(basePackage);
     }
 
diff --git a/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/wrapper/OpenApiClientGeneratorWrapper.java b/client/deployment/src/main/java/io/quarkiverse/openapi/generator/deployment/wrapper/OpenApiClientGeneratorWrapper.java
@@ -111,6 +111,7 @@ private void setDefaults() {
         this.configurator.addAdditionalProperty("verbose", FALSE);
         this.configurator.addAdditionalProperty(CodegenConstants.SERIALIZABLE_MODEL, FALSE);
         this.configurator.addAdditionalProperty("equals-hashcode", TRUE);
+        this.configurator.addAdditionalProperty("use-dynamic-url", FALSE);
     }
 
     /**
@@ -323,6 +324,11 @@ public OpenApiClientGeneratorWrapper withModelNamePrefix(final String modelNameP
         return this;
     }
 
+    public OpenApiClientGeneratorWrapper withUseDynamicUrl(final Boolean useDynamicUrl) {
+        this.configurator.addAdditionalProperty("use-dynamic-url", useDynamicUrl);
+        return this;
+    }
+
     /**
      * Main entrypoint, or where to generate the files based on the given base package.
      *
diff --git a/client/deployment/src/main/resources/templates/libraries/microprofile/api.qute b/client/deployment/src/main/resources/templates/libraries/microprofile/api.qute
@@ -126,7 +126,11 @@ public interface {classname} {
         {#if additionalRequestArgs}
             {#for arg in additionalRequestArgs}{!
                 !}{arg}{#if arg_hasNext}, {/if}{/for}{!
-            !}{#if op.hasFormParams || op.allParams},{/if}
+            !}{#if op.allParams || op.hasFormParams},{/if}
+        {/if}
+        {#if is-resteasy-reactive && use-dynamic-url}
+        // See https://quarkus.io/version/3.20/guides/rest-client#dynamic-base-urls
+        @io.quarkus.rest.client.reactive.Url String dynUrl{#if op.allParams || op.hasFormParams},{/if}
         {/if}
         {#if op.hasFormParams}
         {#if is-resteasy-reactive}
diff --git a/client/deployment/src/test/java/io/quarkiverse/openapi/generator/deployment/wrapper/OpenApiClientGeneratorWrapperTest.java b/client/deployment/src/test/java/io/quarkiverse/openapi/generator/deployment/wrapper/OpenApiClientGeneratorWrapperTest.java
diff --git a/docs/modules/ROOT/pages/client.adoc b/docs/modules/ROOT/pages/client.adoc
@@ -199,6 +199,11 @@ quarkus.openapi-generator.codegen.spec.my_openapi_yaml.serializable-model=true
 
 include::./includes/equals-hashcode.adoc[leveloffset=+1, opts=optional]
 
+[[dynamic-url]]
+== Dynamic base URLs
+
+include::./includes/dynamic-url.adoc[leveloffset=+1, opts=optional]
+
 == Known Limitations
 
 === Supported Arguments
diff --git a/docs/modules/ROOT/pages/includes/dynamic-url.adoc b/docs/modules/ROOT/pages/includes/dynamic-url.adoc
@@ -0,0 +1,16 @@
+
+If you need the generated `RestClient` to target different server URLs at runtime—rather than relying solely on the static URL from the application configuration—you can enable dynamic base URL support.
+
+To do so, set the following property in your configuration:
+
+[source,properties]
+----
+quarkus.openapi-generator.codegen.spec.my_openapi_yaml.use-dynamic-url=true
+----
+
+When this property is enabled and `quarkus-rest-client` is present on the classpath, the generator will include a method parameter annotated with `@io.quarkus.rest.client.reactive.Url`. This allows your application to supply the target URL dynamically at runtime.
+
+This feature is particularly useful when integrating with multiple instances of the same API or switching endpoints based on contextual information.
+
+For more details, refer to the official Quarkus documentation:
+https://quarkus.io/version/3.20/guides/rest-client#dynamic-base-urls
diff --git a/docs/modules/ROOT/pages/includes/quarkus-openapi-generator.adoc b/docs/modules/ROOT/pages/includes/quarkus-openapi-generator.adoc
@@ -1279,6 +1279,27 @@ endif::add-copy-button-to-env-var[]
 |boolean
 |
 
+a|icon:lock[title=Fixed at build time] [[quarkus-openapi-generator_quarkus-openapi-generator-codegen-spec-spec-item-use-dynamic-url]] [.property-path]##link:#quarkus-openapi-generator_quarkus-openapi-generator-codegen-spec-spec-item-use-dynamic-url[`quarkus.openapi-generator.codegen.spec."spec-item".use-dynamic-url`]##
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.openapi-generator.codegen.spec."spec-item".use-dynamic-url+++[]
+endif::add-copy-button-to-config-props[]
+
+
+[.description]
+--
+Whether to enable Dynamic URLs on APIs methods. By enabling this property every method on `RestClients` will be annotated with `io.quarkus.rest.client.reactive.Url`.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_SPEC__SPEC_ITEM__USE_DYNAMIC_URL+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_SPEC__SPEC_ITEM__USE_DYNAMIC_URL+++`
+endif::add-copy-button-to-env-var[]
+--
+|boolean
+|`false`
+
 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
@@ -1279,6 +1279,27 @@ endif::add-copy-button-to-env-var[]
 |boolean
 |
 
+a|icon:lock[title=Fixed at build time] [[quarkus-openapi-generator_quarkus-openapi-generator-codegen-spec-spec-item-use-dynamic-url]] [.property-path]##link:#quarkus-openapi-generator_quarkus-openapi-generator-codegen-spec-spec-item-use-dynamic-url[`quarkus.openapi-generator.codegen.spec."spec-item".use-dynamic-url`]##
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.openapi-generator.codegen.spec."spec-item".use-dynamic-url+++[]
+endif::add-copy-button-to-config-props[]
+
+
+[.description]
+--
+Whether to enable Dynamic URLs on APIs methods. By enabling this property every method on `RestClients` will be annotated with `io.quarkus.rest.client.reactive.Url`.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_SPEC__SPEC_ITEM__USE_DYNAMIC_URL+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_OPENAPI_GENERATOR_CODEGEN_SPEC__SPEC_ITEM__USE_DYNAMIC_URL+++`
+endif::add-copy-button-to-env-var[]
+--
+|boolean
+|`false`
+
 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/pom.xml b/docs/pom.xml
@@ -9,7 +9,7 @@
     <relativePath>../pom.xml</relativePath>
   </parent>
   <artifactId>quarkus-openapi-generator-docs</artifactId>
-  <name>Quarkus - OpenAPI Generator - Client - Documentation</name>
+  <name>Quarkus - OpenAPI Generator - Documentation</name>
 
   <dependencies>
     <!-- Make sure the doc is built after the other artifacts -->

Original file line number	Diff line number	Diff line change
`@@ -339,6 +339,9 @@ protected void generate(OpenApiGeneratorOptions options) {`
`339`	`339`	`OpenApiClientGeneratorWrapper.SUPPORTS_ADDITIONAL_PROPERTIES_AS_ATTRIBUTE,`
`340`	`340`	`additionalPropertiesAsAttribute.toString());`
`341`	`341`
	`342`	`+ getValues(smallRyeConfig, openApiFilePath, CodegenConfig.ConfigName.USE_DYNAMIC_URL, Boolean.class)`
	`343`	`+ .ifPresent(generator::withUseDynamicUrl);`
	`344`	`+`
`342`	`345`	`generator.generate(basePackage);`
`343`	`346`	`}`
`344`	`347`
Original file line number	Diff line number	Diff line change
`@@ -111,6 +111,7 @@ private void setDefaults() {`
`111`	`111`	`this.configurator.addAdditionalProperty("verbose", FALSE);`
`112`	`112`	`this.configurator.addAdditionalProperty(CodegenConstants.SERIALIZABLE_MODEL, FALSE);`
`113`	`113`	`this.configurator.addAdditionalProperty("equals-hashcode", TRUE);`
	`114`	`+ this.configurator.addAdditionalProperty("use-dynamic-url", FALSE);`
`114`	`115`	`}`
`115`	`116`
`116`	`117`	`/**`
`@@ -323,6 +324,11 @@ public OpenApiClientGeneratorWrapper withModelNamePrefix(final String modelNameP`
`323`	`324`	`return this;`
`324`	`325`	`}`
`325`	`326`
	`327`	`+ public OpenApiClientGeneratorWrapper withUseDynamicUrl(final Boolean useDynamicUrl) {`
	`328`	`+ this.configurator.addAdditionalProperty("use-dynamic-url", useDynamicUrl);`
	`329`	`+ return this;`
	`330`	`+ }`
	`331`	`+`
`326`	`332`	`/**`
`327`	`333`	`* Main entrypoint, or where to generate the files based on the given base package.`
`328`	`334`	`*`