From e1f0af33022c2d3aac82a6b58ae959884b82237d Mon Sep 17 00:00:00 2001
From: nightcityblade <nightcityblade@gmail.com>
Date: Thu, 13 Aug 2026 11:06:25 +0800
Subject: [PATCH] docs: clarify alpha upstream path syntax

Signed-off-by: nightcityblade <nightcityblade@gmail.com>
---
 docs/docs/configuration/alpha_config.md |  2 +-
 pkg/apis/options/upstreams.go           | 12 +++++++-----
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/docs/configuration/alpha_config.md b/docs/docs/configuration/alpha_config.md
index 680741ba..36df0c1e 100644
--- a/docs/docs/configuration/alpha_config.md
+++ b/docs/docs/configuration/alpha_config.md
@@ -678,7 +678,7 @@ Requests will be proxied to this upstream if the path matches the request path.
 | Field | Type | Description |
 | ----- | ---- | ----------- |
 | `id` | _string_ | ID should be a unique identifier for the upstream.<br/>This value is required for all upstreams. |
-| `path` | _string_ | Path is used to map requests to the upstream server.<br/>The closest match will take precedence and all Paths must be unique.<br/>Path can also take a pattern when used with RewriteTarget.<br/>Path segments can be captured and matched using regular experessions.<br/>Eg:<br/>- `^/foo$`: Match only the explicit path `/foo`<br/>- `^/bar/$`: Match any path prefixed with `/bar/`<br/>- `^/baz/(.*)$`: Match any path prefixed with `/baz` and capture the remaining path for use with RewriteTarget |
+| `path` | _string_ | Path is used to map requests to the upstream server.<br/>The closest match will take precedence and all Paths must be unique.<br/>Without RewriteTarget, Path follows gorilla/mux route syntax.<br/>Eg:<br/>- `/foo`: Match only the explicit path `/foo`<br/>- `/bar/`: Match any path prefixed with `/bar/`<br/>- `/baz/{path:.*}`: Match any path prefixed with `/baz/`<br/>When RewriteTarget is set, Path is treated as a regular expression.<br/>Eg: `^/baz/(.*)$` matches any path prefixed with `/baz` and captures the<br/>remaining path for use with RewriteTarget. |
 | `rewriteTarget` | _string_ | RewriteTarget allows users to rewrite the request path before it is sent to<br/>the upstream server (for an HTTP/HTTPS upstream) or mapped to the filesystem<br/>(for a `file:` upstream).<br/>Use the Path to capture segments for reuse within the rewrite target.<br/>Eg: With a Path of `^/baz/(.*)`, a RewriteTarget of `/foo/$1` would rewrite<br/>the request `/baz/abc/123` to `/foo/abc/123` before proxying to the<br/>upstream server.  Or if the upstream were `file:///app`, a request for<br/>`/baz/info.html` would return the contents of the file `/app/foo/info.html`. |
 | `uri` | _string_ | The URI of the upstream server. This may be an HTTP(S) server of a File<br/>based URL. It may include a path, in which case all requests will be served<br/>under that path.<br/>Eg:<br/>- http://localhost:8080<br/>- https://service.localhost<br/>- https://service.localhost/path<br/>- file://host/path<br/>If the URI's path is "/base" and the incoming request was for "/dir",<br/>the upstream request will be for "/base/dir". |
 | `insecureSkipTLSVerify` | _bool_ | InsecureSkipTLSVerify will skip TLS verification of upstream HTTPS hosts.<br/>This option is insecure and will allow potential Man-In-The-Middle attacks<br/>between OAuth2 Proxy and the upstream server.<br/>Defaults to false. |
diff --git a/pkg/apis/options/upstreams.go b/pkg/apis/options/upstreams.go
index 578ab454..9ededc28 100644
--- a/pkg/apis/options/upstreams.go
+++ b/pkg/apis/options/upstreams.go
@@ -62,12 +62,14 @@ type Upstream struct {
 
 	// Path is used to map requests to the upstream server.
 	// The closest match will take precedence and all Paths must be unique.
-	// Path can also take a pattern when used with RewriteTarget.
-	// Path segments can be captured and matched using regular experessions.
+	// Without RewriteTarget, Path follows gorilla/mux route syntax.
 	// Eg:
-	// - `^/foo$`: Match only the explicit path `/foo`
-	// - `^/bar/$`: Match any path prefixed with `/bar/`
-	// - `^/baz/(.*)$`: Match any path prefixed with `/baz` and capture the remaining path for use with RewriteTarget
+	// - `/foo`: Match only the explicit path `/foo`
+	// - `/bar/`: Match any path prefixed with `/bar/`
+	// - `/baz/{path:.*}`: Match any path prefixed with `/baz/`
+	// When RewriteTarget is set, Path is treated as a regular expression.
+	// Eg: `^/baz/(.*)$` matches any path prefixed with `/baz` and captures the
+	// remaining path for use with RewriteTarget.
 	Path string `yaml:"path,omitempty"`
 
 	// RewriteTarget allows users to rewrite the request path before it is sent to