From 8369708e570632d31f79874281f581ce4b17e130 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Deleuze?= <sdeleuze@vmware.com>
Date: Sun, 16 Oct 2022 20:28:19 +0200
Subject: [PATCH] Document how to use WebJars without webjars-locator-core
 dependency

Closes gh-29322
---
 .../resource/WebJarsResourceResolver.java        |  7 +++++--
 .../resource/WebJarsResourceResolver.java        |  7 +++++--
 src/docs/asciidoc/web/webflux.adoc               | 16 +++++++++++-----
 src/docs/asciidoc/web/webmvc.adoc                | 16 +++++++++++-----
 4 files changed, 32 insertions(+), 14 deletions(-)

diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/resource/WebJarsResourceResolver.java b/spring-webflux/src/main/java/org/springframework/web/reactive/resource/WebJarsResourceResolver.java
index ca5bd89b78e1..461d72dec4a2 100644
--- a/spring-webflux/src/main/java/org/springframework/web/reactive/resource/WebJarsResourceResolver.java
+++ b/spring-webflux/src/main/java/org/springframework/web/reactive/resource/WebJarsResourceResolver.java
@@ -30,8 +30,8 @@
  * attempts to find a matching versioned resource contained in a WebJar JAR file.
  *
  * <p>This allows WebJars.org users to write version agnostic paths in their templates,
- * like {@code <script src="/jquery/jquery.min.js"/>}.
- * This path will be resolved to the unique version {@code <script src="/jquery/1.2.0/jquery.min.js"/>},
+ * like {@code <script src="/webjars/jquery/jquery.min.js"/>}.
+ * This path will be resolved to the unique version {@code <script src="/webjars/jquery/1.2.0/jquery.min.js"/>},
  * which is a better fit for HTTP caching and version management in applications.
  *
  * <p>This also resolves resources for version agnostic HTTP requests {@code "GET /jquery/jquery.min.js"}.
@@ -39,6 +39,9 @@
  * <p>This resolver requires the {@code org.webjars:webjars-locator-core} library
  * on the classpath and is automatically registered if that library is present.
  *
+ * <p>Be aware that {@code WebJarAssetLocator} constructor performs a classpath scanning that
+ * could slow down application startup.
+ *
  * @author Rossen Stoyanchev
  * @author Brian Clozel
  * @since 5.0
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/resource/WebJarsResourceResolver.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/resource/WebJarsResourceResolver.java
index 6e0fca296a04..2d945bca28de 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/resource/WebJarsResourceResolver.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/resource/WebJarsResourceResolver.java
@@ -30,8 +30,8 @@
  * attempts to find a matching versioned resource contained in a WebJar JAR file.
  *
  * <p>This allows WebJars.org users to write version agnostic paths in their templates,
- * like {@code <script src="/jquery/jquery.min.js"/>}.
- * This path will be resolved to the unique version {@code <script src="/jquery/1.2.0/jquery.min.js"/>},
+ * like {@code <script src="/webjars/jquery/jquery.min.js"/>}.
+ * This path will be resolved to the unique version {@code <script src="/webjars/jquery/1.2.0/jquery.min.js"/>},
  * which is a better fit for HTTP caching and version management in applications.
  *
  * <p>This also resolves resources for version agnostic HTTP requests {@code "GET /jquery/jquery.min.js"}.
@@ -39,6 +39,9 @@
  * <p>This resolver requires the {@code org.webjars:webjars-locator-core} library
  * on the classpath and is automatically registered if that library is present.
  *
+ * <p>Be aware that {@code WebJarAssetLocator} constructor performs a classpath scanning that
+ * could slow down application startup.
+ *
  * @author Brian Clozel
  * @since 4.2
  * @see org.springframework.web.servlet.config.annotation.ResourceChainRegistration
diff --git a/src/docs/asciidoc/web/webflux.adoc b/src/docs/asciidoc/web/webflux.adoc
index f86bfdd49ff8..bc96e3c5a47d 100644
--- a/src/docs/asciidoc/web/webflux.adoc
+++ b/src/docs/asciidoc/web/webflux.adoc
@@ -4256,12 +4256,18 @@ Note that, when using both `EncodedResourceResolver` (for example, Gzip, Brotli
 `VersionedResourceResolver`, they must be registered in that order, to ensure content-based
 versions are always computed reliably based on the unencoded file.
 
-https://www.webjars.org/documentation[WebJars] are also supported through the
+For https://www.webjars.org/documentation[WebJars], versioned URLs like
+`/webjars/jquery/1.2.0/jquery.min.js` are the recommended and most efficient way to use them.
+The related resource location is configured out of the box with Spring Boot (or can be configured
+manually via `ResourceHandlerRegistry`) and does not require to add the
+`org.webjars:webjars-locator-core` dependency.
+
+Version-less URLs like `/webjars/jquery/jquery.min.js` are supported through the
 `WebJarsResourceResolver` which is automatically registered when the
-`org.webjars:webjars-locator-core` library is present on the classpath. The resolver can
-re-write URLs to include the version of the jar and can also match against incoming URLs
-without versions -- for example, from `/jquery/jquery.min.js` to
-`/jquery/1.2.0/jquery.min.js`.
+`org.webjars:webjars-locator-core` library is present on the classpath, at the cost of a
+classpath scanning that could slow down application startup. The resolver can re-write URLs to
+include the version of the jar and can also match against incoming URLs without versions
+-- for example, from `/webjars/jquery/jquery.min.js` to `/webjars/jquery/1.2.0/jquery.min.js`.
 
 TIP: The Java configuration based on `ResourceHandlerRegistry` provides further options
 for fine-grained control, e.g. last-modified behavior and optimized resource resolution.
diff --git a/src/docs/asciidoc/web/webmvc.adoc b/src/docs/asciidoc/web/webmvc.adoc
index 9ac7512d8b0b..7c4cabf11652 100644
--- a/src/docs/asciidoc/web/webmvc.adoc
+++ b/src/docs/asciidoc/web/webmvc.adoc
@@ -5870,12 +5870,18 @@ Note that, when using both `EncodedResourceResolver` (for example, for serving g
 brotli-encoded resources) and `VersionResourceResolver`, you must register them in this order.
 That ensures content-based versions are always computed reliably, based on the unencoded file.
 
-https://www.webjars.org/documentation[WebJars] are also supported through the
+For https://www.webjars.org/documentation[WebJars], versioned URLs like
+`/webjars/jquery/1.2.0/jquery.min.js` are the recommended and most efficient way to use them.
+The related resource location is configured out of the box with Spring Boot (or can be configured
+manually via `ResourceHandlerRegistry`) and does not require to add the
+`org.webjars:webjars-locator-core` dependency.
+
+Version-less URLs like `/webjars/jquery/jquery.min.js` are supported through the
 `WebJarsResourceResolver` which is automatically registered when the
-`org.webjars:webjars-locator-core` library is present on the classpath. The resolver can
-re-write URLs to include the version of the jar and can also match against incoming URLs
-without versions -- for example, from `/jquery/jquery.min.js` to
-`/jquery/1.2.0/jquery.min.js`.
+`org.webjars:webjars-locator-core` library is present on the classpath, at the cost of a
+classpath scanning that could slow down application startup. The resolver can re-write URLs to
+include the version of the jar and can also match against incoming URLs without versions
+-- for example, from `/webjars/jquery/jquery.min.js` to `/webjars/jquery/1.2.0/jquery.min.js`.
 
 TIP: The Java configuration based on `ResourceHandlerRegistry` provides further options
 for fine-grained control, e.g. last-modified behavior and optimized resource resolution.