From db9a4b75f3542ed44c03763c7ba1e59a22b6493d Mon Sep 17 00:00:00 2001
From: Georgios Andrianakis <geoand@gmail.com>
Date: Wed, 12 Jun 2024 08:48:24 +0300
Subject: [PATCH] Add documentation about the Quarkus REST's `@Separator`

---
 docs/src/main/asciidoc/rest.adoc | 59 ++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/docs/src/main/asciidoc/rest.adoc b/docs/src/main/asciidoc/rest.adoc
index 4d1fac46866e8..5531dbb5c0001 100644
--- a/docs/src/main/asciidoc/rest.adoc
+++ b/docs/src/main/asciidoc/rest.adoc
@@ -2865,6 +2865,65 @@ public class Endpoint {
 }
 ----
 
+==== Separating Query parameter values
+
+Normally a collection of `String` values is used to capture the values used in multiple occurrences of the same query parameter.
+For example, for the following resource method:
+
+[source,java]
+----
+@Path("hello")
+public static class HelloResource {
+
+    @GET
+    public String hello(@RestQuery("name") List<String> names) {
+        if (names.isEmpty()) {
+            return "hello world";
+        } else {
+            return "hello " + String.join(" ", names);
+        }
+    }
+}
+----
+
+and the following request:
+
+[source,http]
+----
+GET /hello?name=foo&name=bar HTTP/1.1
+----
+
+the `names` variable will contain both `foo` and `bar` and the response will be `hello foo bar`.
+
+It is not uncommon however to need to convert a single query parameter into a collection of values based on some delimiting character. That is where the `@org.jboss.resteasy.reactive.Separator` annotation comes into play.
+
+If we update the resource method to:
+
+[source,java]
+----
+@Path("hello")
+public static class HelloResource {
+
+    @GET
+    public String hello(@RestQuery("name") @Separator(",") List<String> names) {
+        if (names.isEmpty()) {
+            return "hello world";
+        } else {
+            return "hello " + String.join(" ", names);
+        }
+    }
+}
+----
+
+and use the following request:
+
+[source,http]
+----
+GET /hello?name=foo,bar HTTP/1.1
+----
+
+then the response will be `hello foo bar`.
+
 ==== Handling dates
 
 Quarkus REST supports the use of the implementations of `java.time.Temporal` (like `java.time.LocalDateTime`) as query, path, or form params.