Clarify raw vs normalized path usage in Vert.x Core documentation

vertx-core/src/main/asciidoc/http.adoc

@@ -187,6 +187,14 @@ For example, if the request URI was `a/b/c/page.html?param1=abc&param2=xyz
 
 Then the path would be `/a/b/c/page.html`
 
+Note that `HttpServerRequest#path()` returns the raw path as it was sent by the client.
+This value may contain repeated separators such as `//` or path traversal markers like `..`.
+
+If you are using Vert.x Web and need to perform security-sensitive checks or route
+comparisons based on a normalized version of the path, prefer using
+`RoutingContext#normalizedPath()` instead. Vert.x Web applies additional
+transformations to ensure the path is canonicalized before matching routes.
+
 ==== Request query
 
 Use {@link io.vertx.core.http.HttpServerRequest#query} to return the query part of the URI

vertx-core/src/main/java/io/vertx/core/http/HttpRequestHead.java

@@ -28,7 +28,16 @@ public interface HttpRequestHead {
   String uri();
 
   /**
-   * @return The path part of the uri. For example {@code /somepath/somemorepath/someresource.foo}
+   * Returns the path component of the HTTP request URI.
+   * <p>
+   * This is the raw, non-normalized path as received from the client.
+   * It may contain duplicated separators or traversal segments such as {@code ".."}.
+   * <p>
+   * For security-sensitive logic (for example access control, routing or
+   * filesystem checks), applications should prefer using a normalized path
+   * provided by the framework instead of relying on this raw value.
+   *
+   * @return the raw path component of the request URI
    */
   @Nullable
   String path();