fix: URL Path Parameter Encoding Issue

client/deployment/src/main/resources/templates/libraries/microprofile/api.qute

@@ -2,6 +2,7 @@ package {package};
 
 import java.util.List;
 import java.util.Map;
+import io.quarkiverse.openapi.generator.providers.PathParamEncodingParamConverterProvider;
 {#if use-bean-validation}
 {! https://github.com/OpenAPITools/openapi-generator/issues/18974 !}
 import jakarta.validation.Valid;
@@ -22,6 +23,7 @@ import {imp.import};
 @org.eclipse.microprofile.rest.client.inject.RegisterRestClient({#if defaultServerUrl.or('') != ''}baseUri="{defaultServerUrl}", {/if}configKey="{configKey}")
 {/if}
 @io.quarkiverse.openapi.generator.annotations.GeneratedClass(value="{openapi:parseUri(inputSpec)}", tag = "{baseName}")
+@org.eclipse.microprofile.rest.client.annotation.RegisterProvider(PathParamEncodingParamConverterProvider.class)
 {#if enable-security-generation && openapi:hasAuthMethods(operations) }
 @org.eclipse.microprofile.rest.client.annotation.RegisterProvider({package}.auth.CompositeAuthenticationProvider.class)
 @org.eclipse.microprofile.rest.client.annotation.RegisterClientHeaders({package}.auth.AuthenticationPropagationHeadersFactory.class)

client/deployment/src/main/resources/templates/libraries/microprofile/pathParams.qute

@@ -1 +1 @@
-{#if param.isPathParam}@io.quarkiverse.openapi.generator.annotations.GeneratedParam("{param.baseName}") @jakarta.ws.rs.PathParam("{param.baseName}"){param.dataType} {param.paramName}{/if}
+{#if param.isPathParam}@io.quarkiverse.openapi.generator.annotations.GeneratedParam("{param.baseName}"){#if param.dataType == 'String'} @io.quarkiverse.openapi.generator.annotations.EncodedPathParam{/if} @jakarta.ws.rs.PathParam("{param.baseName}"){param.dataType} {param.paramName}{/if}

client/deployment/src/test/java/io/quarkiverse/openapi/generator/deployment/wrapper/OpenApiClientGeneratorWrapperTest.java

@@ -733,6 +733,45 @@ void verifyDynamicUrlAnnotation() throws Exception {
         }
     }
 
+    @Test
+    void verifyPathParamsAreEncoded() throws Exception {
+        List<File> generatedFiles = createGeneratorWrapper("issue-38.yaml")
+                .withEnabledSecurityGeneration(false)
+                .generate("org.issue38");
+
+        Optional<File> file = generatedFiles.stream()
+                .filter(f -> f.getName().endsWith("ConnectorClustersAgentApi.java"))
+                .findAny();
+        assertThat(file).isNotEmpty();
+
+        CompilationUnit compilationUnit = StaticJavaParser.parse(file.orElseThrow());
+        boolean foundRegisterProvider = compilationUnit.findAll(AnnotationExpr.class).stream()
+                .filter(annotation -> annotation.getName().getIdentifier().equals("RegisterProvider"))
+                .anyMatch(annotation -> {
+                    if (annotation instanceof SingleMemberAnnotationExpr singleMemberAnnotationExpr) {
+                        return singleMemberAnnotationExpr.getMemberValue().isClassExpr()
+                                && singleMemberAnnotationExpr.getMemberValue().asClassExpr().getType().asString()
+                                        .equals("PathParamEncodingParamConverterProvider");
+                    }
+                    if (annotation instanceof NormalAnnotationExpr normalAnnotationExpr) {
+                        return normalAnnotationExpr.getPairs().stream()
+                                .filter(pair -> pair.getNameAsString().equals("value"))
+                                .map(MemberValuePair::getValue)
+                                .anyMatch(value -> value.isClassExpr()
+                                        && value.asClassExpr().getType().asString()
+                                                .equals("PathParamEncodingParamConverterProvider"));
+                    }
+                    return false;
+                });
+        assertThat(foundRegisterProvider).isTrue();
+
+        boolean foundEncodedPathParam = compilationUnit.findAll(MethodDeclaration.class).stream()
+                .flatMap(method -> method.getParameters().stream())
+                .anyMatch(parameter -> parameter.getAnnotationByName("PathParam").isPresent()
+                        && parameter.getAnnotationByName("EncodedPathParam").isPresent());
+        assertThat(foundEncodedPathParam).isTrue();
+    }
+
     @Test
     void verifyAllowAdditionalPropertiesIfNotPresent() throws Exception {
         List<File> generatedFiles = createGeneratorWrapperReactive("issue-1185.json")

client/runtime/src/main/java/io/quarkiverse/openapi/generator/annotations/EncodedPathParam.java

@@ -0,0 +1,15 @@
+package io.quarkiverse.openapi.generator.annotations;
+
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a generated path parameter so the client can safely encode path segments.
+ */
+@Retention(RUNTIME)
+@Target(PARAMETER)
+public @interface EncodedPathParam {
+}

client/runtime/src/main/java/io/quarkiverse/openapi/generator/providers/PathParamEncodingParamConverterProvider.java

@@ -0,0 +1,122 @@
+package io.quarkiverse.openapi.generator.providers;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Type;
+import java.nio.charset.StandardCharsets;
+import java.util.Locale;
+
+import jakarta.ws.rs.ext.ParamConverter;
+import jakarta.ws.rs.ext.ParamConverterProvider;
+import jakarta.ws.rs.ext.Provider;
+
+import io.quarkiverse.openapi.generator.annotations.EncodedPathParam;
+
+/**
+ * JAX-RS param converter provider used by generated REST clients for path parameters.
+ * <p>
+ * It percent-encodes reserved characters for path parameter values, while preserving already-encoded
+ * percent triplets such as {@code %2F}. That allows callers to pass either raw paths like
+ * {@code mygroup/myproject/backend} or already-encoded values like {@code mygroup%2Fmyproject%2Fbackend}
+ * without producing invalid double-encoded URLs.
+ */
+@Provider
+public class PathParamEncodingParamConverterProvider implements ParamConverterProvider {
+
+    private static final ParamConverter<String> STRING_PATH_PARAM_CONVERTER = new ParamConverter<>() {
+        @Override
+        public String fromString(String value) {
+            return value;
+        }
+
+        @Override
+        public String toString(String value) {
+            return encodePathParamValuePreservingEscapes(value);
+        }
+    };
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public <T> ParamConverter<T> getConverter(Class<T> rawType, Type genericType, Annotation[] annotations) {
+        if (rawType != String.class || !hasEncodedPathParam(annotations)) {
+            return null;
+        }
+        return (ParamConverter<T>) STRING_PATH_PARAM_CONVERTER;
+    }
+
+    /**
+     * Encodes a path-parameter value using UTF-8 percent encoding, preserving existing escape sequences.
+     * <p>
+     * This treats {@code /} as data and encodes it to {@code %2F}, which is what generated clients need for
+     * path-parameter values that may span multiple raw segments.
+     *
+     * @param value the raw or already-encoded path-parameter value
+     * @return the encoded path-parameter value, or {@code null} if the input was {@code null}
+     */
+    static String encodePathParamValuePreservingEscapes(String value) {
+        if (value == null) {
+            return null;
+        }
+
+        StringBuilder encoded = new StringBuilder(value.length());
+        for (int i = 0; i < value.length();) {
+            char ch = value.charAt(i);
+            if (ch == '%' && i + 2 < value.length() && isHexDigit(value.charAt(i + 1)) && isHexDigit(value.charAt(i + 2))) {
+                encoded.append(ch).append(value.charAt(i + 1)).append(value.charAt(i + 2));
+                i += 3;
+                continue;
+            }
+
+            int codePoint = value.codePointAt(i);
+            if (isUnreserved(codePoint)) {
+                encoded.appendCodePoint(codePoint);
+            } else {
+                byte[] bytes = new String(Character.toChars(codePoint)).getBytes(StandardCharsets.UTF_8);
+                for (byte b : bytes) {
+                    encoded.append('%');
+                    int unsigned = b & 0xFF;
+                    if (unsigned < 0x10) {
+                        encoded.append('0');
+                    }
+                    encoded.append(Integer.toHexString(unsigned).toUpperCase(Locale.ROOT));
+                }
+            }
+            i += Character.charCount(codePoint);
+        }
+
+        return encoded.toString();
+    }
+
+    /**
+     * Returns {@code true} when the parameter was generated as a path parameter that should be encoded.
+     */
+    private static boolean hasEncodedPathParam(Annotation[] annotations) {
+        if (annotations == null) {
+            return false;
+        }
+        for (Annotation annotation : annotations) {
+            if (annotation.annotationType() == EncodedPathParam.class) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * RFC 3986 unreserved characters can remain unchanged in a path segment.
+     */
+    private static boolean isUnreserved(int codePoint) {
+        return codePoint >= 'a' && codePoint <= 'z'
+                || codePoint >= 'A' && codePoint <= 'Z'
+                || codePoint >= '0' && codePoint <= '9'
+                || codePoint == '-' || codePoint == '.' || codePoint == '_' || codePoint == '~';
+    }
+
+    /**
+     * Checks whether a character is a hexadecimal digit.
+     */
+    private static boolean isHexDigit(char ch) {
+        return (ch >= '0' && ch <= '9')
+                || (ch >= 'a' && ch <= 'f')
+                || (ch >= 'A' && ch <= 'F');
+    }
+}

client/runtime/src/test/java/io/quarkiverse/openapi/generator/providers/PathParamEncodingParamConverterProviderTest.java

@@ -0,0 +1,51 @@
+package io.quarkiverse.openapi.generator.providers;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
+
+import org.junit.jupiter.api.Test;
+
+import io.quarkiverse.openapi.generator.annotations.EncodedPathParam;
+
+class PathParamEncodingParamConverterProviderTest {
+
+    private final PathParamEncodingParamConverterProvider provider = new PathParamEncodingParamConverterProvider();
+
+    @Test
+    void encodesRawPathSegmentsWithoutDoubleEncodingEscapes() throws Exception {
+        Annotation[] annotations = encodedPathParamAnnotations();
+
+        var converter = provider.getConverter(String.class, String.class, annotations);
+        assertEquals("mygroup%2Fmyproject%2Fbackend", converter.toString("mygroup/myproject/backend"));
+        assertEquals("mygroup%2Fmyproject%2Fbackend", converter.toString("mygroup%2Fmyproject%2Fbackend"));
+        assertEquals("space%20and%2Bplus", converter.toString("space and+plus"));
+        assertEquals("caf%C3%A9", converter.toString("café"));
+    }
+
+    @Test
+    void doesNotApplyToRegularParameters() {
+        assertNull(provider.getConverter(String.class, String.class, new Annotation[0]));
+    }
+
+    @Test
+    void reusesTheSameConverterInstance() throws Exception {
+        Annotation[] annotations = encodedPathParamAnnotations();
+
+        var converter = provider.getConverter(String.class, String.class, annotations);
+        assertSame(converter, provider.getConverter(String.class, String.class, annotations));
+    }
+
+    private Annotation[] encodedPathParamAnnotations() throws Exception {
+        Method method = getClass().getDeclaredMethod("sample", String.class);
+        return method.getParameters()[0].getAnnotations();
+    }
+
+    @SuppressWarnings("unused")
+    private void sample(@EncodedPathParam String value) {
+        value.length();
+    }
+}