From dabc3fe2d80672d95b132d45fb6e473768c4660a Mon Sep 17 00:00:00 2001
From: halo <dongjin778@naver.com>
Date: Wed, 10 Jun 2026 08:49:32 +0900
Subject: [PATCH] docs: document naming convention and YAML usage for custom
 route predicates (GH-3463)

The Developer Guide showed how to write a custom RoutePredicateFactory and how to
reference custom GatewayFilters in configuration, but had no equivalent guidance
for predicates. Added a "Naming Custom Predicates And References In Configuration"
section right after the custom predicate class example, covering:

- The RoutePredicateFactory suffix naming convention
- Shortcut and fully-expanded YAML configuration examples
- A WARNING about unsupported non-standard naming

Closes gh-3463

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../developer-guide.adoc                      | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/developer-guide.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/developer-guide.adoc
index 709b75519..703c990b9 100644
--- a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/developer-guide.adoc
+++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/developer-guide.adoc
@@ -37,6 +37,54 @@ public class MyRoutePredicateFactory extends AbstractRoutePredicateFactory<MyRou
 
 }
 ----
+[[naming-custom-predicates-and-references-in-configuration]]
+=== Naming Custom Predicates And References In Configuration
+
+Custom route predicate factory class names should end in `RoutePredicateFactory`.
+
+For example, to reference a predicate named `My` in configuration files, the factory must be in a class named `MyRoutePredicateFactory`:
+
+.application.yml
+[source,yaml]
+----
+spring:
+  cloud:
+    gateway:
+      server:
+        webflux:
+          routes:
+          - id: my_route
+            uri: https://example.org
+            predicates:
+            - My=argument
+----
+
+Or using fully expanded arguments:
+
+.application.yml
+[source,yaml]
+----
+spring:
+  cloud:
+    gateway:
+      server:
+        webflux:
+          routes:
+          - id: my_route
+            uri: https://example.org
+            predicates:
+            - name: My
+              args:
+                myArg: argument
+----
+
+The predicate factory must override `shortcutFieldOrder()` to define the order of shortcut arguments and `Config` fields must match the keys used in the `args` map.
+
+WARNING: It is possible to create a predicate named without the `RoutePredicateFactory` suffix.
+Such a predicate could be referenced by its full class name (minus the package) in configuration files.
+This is **not** a supported naming convention and this syntax may be removed in future releases.
+Please update the predicate name to be compliant.
+
 [[writing-custom-gatewayfilter-factories]]
 == Writing Custom GatewayFilter Factories