From 5d5476fa6ecc72e328529a4e4bffac2c39bb3974 Mon Sep 17 00:00:00 2001
From: halo <dongjin778@naver.com>
Date: Wed, 10 Jun 2026 05:48:22 +0900
Subject: [PATCH] GH-1949: Document that overriding discovery locator filters
 replaces all defaults

Add an IMPORTANT callout to make it clear that setting
spring.cloud.gateway.discovery.locator.filters replaces the entire
default filter list, meaning the RewritePath filter must be explicitly
re-declared or downstream services will receive the unstripped path and
return 404.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../the-discoveryclient-route-definition-locator.adoc    | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/the-discoveryclient-route-definition-locator.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/the-discoveryclient-route-definition-locator.adoc
index 707d6b211..5a78b9d66 100644
--- a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/the-discoveryclient-route-definition-locator.adoc
+++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/the-discoveryclient-route-definition-locator.adoc
@@ -19,7 +19,14 @@ The default filter is a rewrite path filter with the regex `/serviceId/?(?<remai
 This strips the service ID from the path before the request is sent downstream.
 
 If you want to customize the predicates or filters used by the `DiscoveryClient` routes, set `spring.cloud.gateway.discovery.locator.predicates[x]` and `spring.cloud.gateway.discovery.locator.filters[y]`.
-When doing so, you need to make sure to include the default predicate and filter shown earlier, if you want to retain that functionality.
+
+[IMPORTANT]
+====
+Setting `spring.cloud.gateway.discovery.locator.filters` *replaces* the entire default filter list.
+If you only add your own filters without re-declaring `RewritePath`, the service ID will *not* be stripped from the path and requests will fail with a `404` on the downstream service.
+Always include the default `RewritePath` filter when defining custom filters, as shown in the examples below.
+====
+
 The following examples shows what this looks like in properties and yaml format:
 
 .application.properties