fix: URL Path Parameter Encoding Issue

[matheusandre1]

Many thanks for submitting your Pull Request ❤️!

Please make sure that your PR meets the following requirements:

• You have read the contributors guide
• Your code is properly formatted according to our code style
• Pull Request title contains the target branch if not targeting main: [0.9.x] Subject
• Pull Request contains link to the issue Closes: URL Path Parameter Encoding Issue #1460
• Pull Request contains link to any dependent or related Pull Request
• Pull Request contains description of the issue
• Pull Request does not include fixes for issues other than the main ticket

How to backport a pull request to a different branch?

In order to automatically create a backporting pull request please add one or more labels having the following format backport-<branch-name>, where <branch-name> is the name of the branch where the pull request must be backported to (e.g., backport-quarkus2 to backport the original PR to the quarkus2 branch).

NOTE: backporting is an action aiming to move a change (usually a commit) from a branch (usually the main one) to another one, which is generally referring to a still maintained release branch. Keeping it simple: it is about to move a specific change or a set of them from one branch to another.

Once the original pull request is successfully merged, the automated action will create one backporting pull request per each label (with the previous format) that has been added.

If something goes wrong, the author will be notified and at this point a manual backporting is needed.

NOTE: this automated backporting is triggered whenever a pull request on main branch is labeled or closed, but both conditions must be satisfied to get the new PR created.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a MicroProfile REST client provider and annotation to ensure generated client path parameters are percent-encoded correctly (without double-encoding already-encoded %XX sequences), addressing the URL path parameter encoding issue (Closes #1460).

Changes:

• Introduces @EncodedPathParam and a ParamConverterProvider to encode path parameter values while preserving existing percent-escapes.
• Updates MicroProfile templates to register the provider and mark generated @PathParam parameters for encoding.
• Adds runtime and deployment tests to validate encoding behavior and generator output.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
client/runtime/src/main/java/io/quarkiverse/openapi/generator/providers/PathParamEncodingParamConverterProvider.java	Adds the JAX-RS ParamConverterProvider implementing “encode but don’t double-encode” behavior.
client/runtime/src/main/java/io/quarkiverse/openapi/generator/annotations/EncodedPathParam.java	Adds marker annotation used to opt-in path param encoding for generated clients.
client/runtime/src/test/java/io/quarkiverse/openapi/generator/providers/PathParamEncodingParamConverterProviderTest.java	Adds unit tests for encoding + instance reuse behavior.
client/deployment/src/main/resources/templates/libraries/microprofile/api.qute	Registers the new provider on generated client APIs.
client/deployment/src/main/resources/templates/libraries/microprofile/pathParams.qute	Marks generated path params with @EncodedPathParam.
client/deployment/src/test/java/io/quarkiverse/openapi/generator/deployment/wrapper/OpenApiClientGeneratorWrapperTest.java	Adds generator-level test to confirm provider registration and annotation emission.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The Javadoc says this encodes a single path segment, but the intended/validated usage includes values containing / (multiple segments) which are encoded to %2F (see tests). Please update the Javadoc (and potentially the method name) to reflect that this encodes an entire path-parameter value and will percent-encode / as well, to avoid misleading API semantics.

[Copilot]

Using toUpperCase() without an explicit locale is generally discouraged since it can be locale-sensitive. While hex digits are typically safe, it’s more robust to use a locale-stable conversion (e.g., toUpperCase(Locale.ROOT)) or a dedicated hex-uppercase mapping.

[Copilot]

@EncodedPathParam is applied to all path parameters, but PathParamEncodingParamConverterProvider currently only returns a converter when rawType == String.class. This makes the marker annotation misleading for non-String path params (it suggests encoding will happen when it won’t). Either (mandatory) emit @EncodedPathParam only for String path params in the template, or (alternative) extend the provider to support other raw types by delegating to their normal string conversion and then applying the percent-encoding.

Suggested change

	{#if param.isPathParam}@io.quarkiverse.openapi.generator.annotations.GeneratedParam("{param.baseName}") @io.quarkiverse.openapi.generator.annotations.EncodedPathParam @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}

[Copilot]

This assertion is a brittle substring check; it can pass due to an import or comment even if the API is not actually annotated with @RegisterProvider(PathParamEncodingParamConverterProvider.class). Since you already parse with JavaParser, prefer asserting structurally (e.g., check for the RegisterProvider annotation with the expected class argument) to make the test resilient to formatting/import changes.

Suggested change

	assertThat(Files.readString(file.orElseThrow().toPath()))
	.contains("PathParamEncodingParamConverterProvider");
	boolean foundRegisterProvider = compilationUnit.findAll(AnnotationExpr.class).stream()
	.filter(annotation -> annotation.getNameAsString().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();