Document how to use WebJars without webjars-locator-core dependency

Closes gh-29322

Author: sdeleuze

spring-webflux/src/main/java/org/springframework/web/reactive/resource/WebJarsResourceResolver.java

@@ -30,15 +30,18 @@
  * 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"}.
  *
  * <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

spring-webmvc/src/main/java/org/springframework/web/servlet/resource/WebJarsResourceResolver.java

@@ -30,15 +30,18 @@
  * 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"}.
  *
  * <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

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.

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.