From 33c02390ab47b00eb464b11714310cb1480960a0 Mon Sep 17 00:00:00 2001
From: CheHyeonYeong <gusdudco6@naver.com>
Date: Fri, 27 Mar 2026 17:09:16 +0900
Subject: [PATCH] Document Path predicate fully expanded argument format

Add documentation for using the Path predicate with fully expanded
arguments, including indexed key notation (patterns.0, patterns.1)
for list parameters. This clarifies the naming convention when
configuring routes via the Actuator API or programmatically.

Fixes gh-3523

Signed-off-by: CheHyeonYeong <gusdudco6@naver.com>
---
 .../request-predicates-factories.adoc         | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/request-predicates-factories.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/request-predicates-factories.adoc
index 6e493e86c1..6a64dd4ba7 100644
--- a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/request-predicates-factories.adoc
+++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/request-predicates-factories.adoc
@@ -208,6 +208,52 @@ This route matches if the request path was, for example: `/red/1` or `/red/1/` o
 
 If `matchTrailingSlash` is set to `false`, then request path `/red/1/` will not be matched.
 
+[[path-route-predicate-factory-expanded-arguments]]
+=== Fully Expanded Arguments
+
+When using the fully expanded argument format (for example, when configuring routes via the Actuator API or programmatically), the `Path` predicate uses indexed keys for list parameters. The following example shows the fully expanded configuration:
+
+.application.yml
+[source,yaml]
+----
+spring:
+  cloud:
+    gateway:
+      server:
+        webflux:
+          routes:
+          - id: path_route
+            uri: https://example.org
+            predicates:
+            - name: Path
+              args:
+                patterns.0: /red/{segment}
+                patterns.1: /blue/{segment}
+                matchTrailingSlash: false
+----
+
+When posting route definitions via the Actuator API, use the same indexed notation in the JSON request body:
+
+[source,json]
+----
+{
+  "id": "path_route",
+  "uri": "https://example.org",
+  "predicates": [
+    {
+      "name": "Path",
+      "args": {
+        "patterns.0": "/red/{segment}",
+        "patterns.1": "/blue/{segment}",
+        "matchTrailingSlash": "false"
+      }
+    }
+  ]
+}
+----
+
+NOTE: The `args` map accepts only `String` key-value pairs. List parameters like `patterns` must be specified using indexed keys (`patterns.0`, `patterns.1`, etc.) rather than JSON arrays. This indexed notation is automatically converted to a `List<String>` when the predicate is configured.
+
 If you have set `spring.webflux.base-path` property, this will influence the path matching. The property value will be automatically prepended to the path patterns. For example, with `spring.webflux.base-path=/app` and a path pattern of `/red/\{segment\}`, the full pattern used for matching would be `/app/red/\{segment\}`.
 
 This predicate extracts the URI template variables (such as `segment`, defined in the preceding example) as a map of names and values and places it in the `ServerWebExchange.getAttributes()` with a key defined in `ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE`.