Use javadoc macro

Closes gh-15386

Author: rwinch

docs/antora-playbook.yml

@@ -24,6 +24,7 @@ asciidoc:
   extensions:
     - '@asciidoctor/tabs'
     - '@springio/asciidoctor-extensions'
+    - '@springio/asciidoctor-extensions/javadoc-extension'
 urls:
   latest_version_segment_strategy: redirect:to
   latest_version_segment: ''

docs/antora.yml

@@ -6,7 +6,7 @@ nav:
 ext:
   collector:
     run:
-      command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-security-docs:generateAntoraYml
+      command: gradlew -q -PbuildSrc.skipTests=true :spring-security-docs:generateAntoraResources
       local: true
     scan:
       dir: ./build/generated-antora-resources

docs/modules/ROOT/nav.adoc

@@ -8,6 +8,7 @@
 * xref:migration/index.adoc[Migrating to 6.2]
 ** xref:migration/authorization.adoc[Authorization Changes]
 * xref:getting-spring-security.adoc[Getting Spring Security]
+* xref:attachment$api/java/index.html[Javadoc]
 * xref:features/index.adoc[Features]
 ** xref:features/authentication/index.adoc[Authentication]
 *** xref:features/authentication/password-storage.adoc[Password Storage]

docs/modules/ROOT/pages/features/authentication/password-storage.adoc

@@ -598,7 +598,7 @@ With the above configuration, when a password manager navigates to `/.well-known
 There are some scenarios where you need to check whether a password has been compromised, for example, if you are creating an application that deals with sensitive data, it is often needed that you perform some check on user's passwords in order to assert its reliability.
 One of these checks can be if the password has been compromised, usually because it has been found in a https://wikipedia.org/wiki/Data_breach[data breach].
 
-To facilitate that, Spring Security provides integration with the https://haveibeenpwned.com/API/v3#PwnedPasswords[Have I Been Pwned API] via the {security-api-url}org/springframework/security/core/password/HaveIBeenPwnedRestApiPasswordChecker.html[`HaveIBeenPwnedRestApiPasswordChecker` implementation] of the {security-api-url}org/springframework/security/core/password/CompromisedPasswordChecker.html[`CompromisedPasswordChecker` interface].
+To facilitate that, Spring Security provides integration with the https://haveibeenpwned.com/API/v3#PwnedPasswords[Have I Been Pwned API] via the javadoc:org.springframework.security.web.authentication.password.HaveIBeenPwnedRestApiPasswordChecker[] implementation of the javadoc:org.springframework.security.authentication.password.CompromisedPasswordChecker[] interface.
 
 You can either use the `CompromisedPasswordChecker` API by yourself or, if you are using xref:servlet/authentication/passwords/dao-authentication-provider.adoc[the `DaoAuthenticationProvider]` via xref:servlet/authentication/passwords/index.adoc[Spring Security authentication mechanisms], you can provide a `CompromisedPasswordChecker` bean, and it will be automatically picked up by Spring Security configuration.
 

docs/modules/ROOT/pages/features/integrations/cryptography.adoc

@@ -8,9 +8,9 @@ The code is distributed as part of the core module but has no dependencies on an
 
 [[spring-security-crypto-encryption]]
 == Encryptors
-The {security-api-url}org/springframework/security/crypto/encrypt/Encryptors.html[`Encryptors`] class provides factory methods for constructing symmetric encryptors.
-This class lets you create {security-api-url}org/springframework/security/crypto/encrypt/BytesEncryptor.html[`BytesEncryptor`] instances to encrypt data in raw `byte[]` form.
-You can also construct {security-api-url}org/springframework/security/crypto/encrypt/TextEncryptor.html[TextEncryptor] instances to encrypt text strings.
+The javadoc:org.springframework.security.crypto.encrypt.Encryptors[] class provides factory methods for constructing symmetric encryptors.
+This class lets you create javadoc:org.springframework.security.crypto.encrypt.BytesEncryptor[] instances to encrypt data in raw `byte[]` form.
+You can also construct javadoc:org.springframework.security.crypto.encrypt.TextEncryptor[] instances to encrypt text strings.
 Encryptors are thread-safe.
 
 [NOTE]
@@ -101,9 +101,9 @@ Encrypted results are returned as hex-encoded strings for easy storage on the fi
 
 [[spring-security-crypto-keygenerators]]
 == Key Generators
-The {security-api-url}org/springframework/security/crypto/keygen/KeyGenerators.html[`KeyGenerators`] class provides a number of convenience factory methods for constructing different types of key generators.
-By using this class, you can create a {security-api-url}org/springframework/security/crypto/keygen/BytesKeyGenerator.html[`BytesKeyGenerator`] to generate `byte[]` keys.
-You can also construct a {security-api-url}org/springframework/security/crypto/keygen/StringKeyGenerator.html`[StringKeyGenerator]` to generate string keys.
+The javadoc:org.springframework.security.crypto.keygen.KeyGenerators[] class provides a number of convenience factory methods for constructing different types of key generators.
+By using this class, you can create a javadoc:org.springframework.security.crypto.keygen.BytesKeyGenerator[] to generate `byte[]` keys.
+You can also construct a javadoc:org.springframework.security.crypto.keygen.StringKeyGenerator[] to generate string keys.
 `KeyGenerators` is a thread-safe class.
 
 === BytesKeyGenerator

docs/modules/ROOT/pages/reactive/authentication/concurrent-sessions-control.adoc

@@ -4,7 +4,7 @@
 Similar to xref:servlet/authentication/session-management.adoc#ns-concurrent-sessions[Servlet's Concurrent Sessions Control], Spring Security also provides support to limit the number of concurrent sessions a user can have in a Reactive application.
 
 When you set up Concurrent Sessions Control in Spring Security, it monitors authentications carried out through Form Login, xref:reactive/oauth2/login/index.adoc[OAuth 2.0 Login], and HTTP Basic authentication by hooking into the way those authentication mechanisms handle authentication success.
-More specifically, the session management DSL will add the {security-api-url}org/springframework/security/web/server/authentication/ConcurrentSessionControlServerAuthenticationSuccessHandler.html[ConcurrentSessionControlServerAuthenticationSuccessHandler] and the {security-api-url}org/springframework/security/web/server/authentication/RegisterSessionServerAuthenticationSuccessHandler.html[RegisterSessionServerAuthenticationSuccessHandler] to the list of `ServerAuthenticationSuccessHandler` used by the authentication filter.
+More specifically, the session management DSL will add the javadoc:org.springframework.security.web.server.authentication.ConcurrentSessionControlServerAuthenticationSuccessHandler[] and the javadoc:org.springframework.security.web.server.authentication.RegisterSessionServerAuthenticationSuccessHandler[] to the list of `ServerAuthenticationSuccessHandler` used by the authentication filter.
 
 The following sections contains examples of how to configure Concurrent Sessions Control.
 
@@ -197,9 +197,9 @@ If you also need to invalidate the session against the Identity Provider you mus
 [[concurrent-sessions-control-custom-strategy]]
 == Handling Maximum Number of Sessions Exceeded
 
-By default, when the maximum number of sessions is exceeded, the least recently used session(s) will be expired by using the {security-api-url}org/springframework/security/web/server/authentication/session/InvalidateLeastUsedMaximumSessionsExceededHandler.html[InvalidateLeastUsedMaximumSessionsExceededHandler].
-Spring Security also provides another implementation that prevents the user from creating new sessions by using the {security-api-url}org/springframework/security/web/server/authentication/session/PreventLoginMaximumSessionsExceededHandler.html[PreventLoginMaximumSessionsExceededHandler].
-If you want to use your own strategy, you can provide a different implementation of {security-api-url}org/springframework/security/web/server/authentication/session/ServerMaximumSessionsExceededHandler.html[ServerMaximumSessionsExceededHandler].
+By default, when the maximum number of sessions is exceeded, the least recently used session(s) will be expired by using the javadoc:org.springframework.security.web.server.authentication.InvalidateLeastUsedServerMaximumSessionsExceededHandler[].
+Spring Security also provides another implementation that prevents the user from creating new sessions by using the javadoc:org.springframework.security.web.server.authentication.PreventLoginServerMaximumSessionsExceededHandler[].
+If you want to use your own strategy, you can provide a different implementation of javadoc:org.springframework.security.web.server.authentication.ServerMaximumSessionsExceededHandler[].
 
 .Configuring maximumSessionsExceededHandler
 [tabs]
@@ -254,9 +254,9 @@ open fun reactiveSessionRegistry(): ReactiveSessionRegistry {
 [[reactive-concurrent-sessions-control-specify-session-registry]]
 == Specifying a `ReactiveSessionRegistry`
 
-In order to keep track of the user's sessions, Spring Security uses a {security-api-url}org/springframework/security/core/session/ReactiveSessionRegistry.html[ReactiveSessionRegistry], and, every time a user logs in, their session information is saved.
+In order to keep track of the user's sessions, Spring Security uses a javadoc:org.springframework.security.core.session.ReactiveSessionRegistry[], and, every time a user logs in, their session information is saved.
 
-Spring Security ships with {security-api-url}org/springframework/security/core/session/InMemoryReactiveSessionRegistry.html[InMemoryReactiveSessionRegistry] implementation of `ReactiveSessionRegistry`.
+Spring Security ships with javadoc:org.springframework.security.core.session.InMemoryReactiveSessionRegistry[] implementation of `ReactiveSessionRegistry`.
 
 To specify a `ReactiveSessionRegistry` implementation you can either declare it as a bean:
 

docs/modules/ROOT/pages/reactive/oauth2/resource-server/bearer-tokens.adoc

@@ -41,7 +41,7 @@ return http {
 == Bearer Token Propagation
 
 Now that you have a bearer token, you can pass that to downstream services.
-This is possible with `{security-api-url}org/springframework/security/oauth2/server/resource/web/reactive/function/client/ServerBearerExchangeFilterFunction.html[ServerBearerExchangeFilterFunction]`:
+This is possible with javadoc:org.springframework.security.oauth2.server.resource.web.reactive.function.client.ServerBearerExchangeFilterFunction[]:
 
 [tabs]
 ======
@@ -70,7 +70,7 @@ fun rest(): WebClient {
 ----
 ======
 
-When the `WebClient` shown in the preceding example performs requests, Spring Security looks up the current `Authentication` and extract any `{security-api-url}org/springframework/security/oauth2/core/AbstractOAuth2Token.html[AbstractOAuth2Token]` credential.
+When the `WebClient` shown in the preceding example performs requests, Spring Security looks up the current `Authentication` and extract any javadoc:org.springframework.security.oauth2.core.AbstractOAuth2Token[] credential.
 Then, it propagates that token in the `Authorization` header -- for example:
 
 [tabs]

docs/modules/ROOT/pages/reactive/oauth2/resource-server/jwt.adoc

@@ -234,7 +234,7 @@ fun jwtDecoder(): ReactiveJwtDecoder {
 
 [NOTE]
 ====
-Calling `{security-api-url}org/springframework/security/oauth2/jwt/ReactiveJwtDecoders.html#fromIssuerLocation-java.lang.String-[ReactiveJwtDecoders#fromIssuerLocation]` invokes the Provider Configuration or Authorization Server Metadata endpoint to derive the JWK Set URI.
+Calling javadoc:org.springframework.security.oauth2.jwt.ReactiveJwtDecoders#fromIssuerLocation-java.lang.String-[ReactiveJwtDecoders#fromIssuerLocation] invokes the Provider Configuration or Authorization Server Metadata endpoint to derive the JWK Set URI.
 If the application does not expose a `ReactiveJwtDecoder` bean, Spring Boot exposes the above default one.
 ====
 

docs/modules/ROOT/pages/reactive/oauth2/resource-server/opaque-token.adoc

@@ -68,7 +68,7 @@ Given an Opaque Token, Resource Server:
 . Inspects the response for an `{ 'active' : true }` attribute.
 . Maps each scope to an authority with a prefix of `SCOPE_`.
 
-By default, the resulting `Authentication#getPrincipal` is a Spring Security `{security-api-url}org/springframework/security/oauth2/core/OAuth2AuthenticatedPrincipal.html[OAuth2AuthenticatedPrincipal]` object, and `Authentication#getName` maps to the token's `sub` property, if one is present.
+By default, the resulting `Authentication#getPrincipal` is a Spring Security javadoc:org.springframework.security.oauth2.core.OAuth2AuthenticatedPrincipal[] object, and `Authentication#getName` maps to the token's `sub` property, if one is present.
 
 From here, you may want to jump to:
 

docs/modules/ROOT/pages/reactive/test/web/oauth2.adoc

@@ -956,7 +956,7 @@ client
 ----
 ======
 
-You can also specify a complete `Jwt`, for which `{security-api-url}org/springframework/security/oauth2/jwt/Jwt.Builder.html[Jwt.Builder]` is quite handy:
+You can also specify a complete `Jwt`, for which javadoc:org.springframework.security.oauth2.jwt.Jwt$Builder[] is quite handy:
 
 [tabs]
 ======

docs/modules/ROOT/pages/servlet/architecture.adoc

@@ -118,7 +118,7 @@ image::{figures}/filterchainproxy.png[]
 [[servlet-securityfilterchain]]
 == SecurityFilterChain
 
-{security-api-url}org/springframework/security/web/SecurityFilterChain.html[`SecurityFilterChain`]  is used by <<servlet-filterchainproxy>> to determine which Spring Security `Filter` instances should be invoked for the current request.
+javadoc:org.springframework.security.web.SecurityFilterChain[]  is used by <<servlet-filterchainproxy>> to determine which Spring Security `Filter` instances should be invoked for the current request.
 
 The following image shows the role of `SecurityFilterChain`.
 
@@ -392,7 +392,7 @@ public FilterRegistrationBean<TenantFilter> tenantFilterRegistration(TenantFilte
 == Handling Security Exceptions
 
 
-The {security-api-url}org/springframework/security/web/access/ExceptionTranslationFilter.html[`ExceptionTranslationFilter`] allows translation of {security-api-url}org/springframework/security/access/AccessDeniedException.html[`AccessDeniedException`] and {security-api-url}/org/springframework/security/core/AuthenticationException.html[`AuthenticationException`] into HTTP responses.
+The javadoc:org.springframework.security.web.access.ExceptionTranslationFilter[] allows translation of javadoc:org.springframework.security.access.AccessDeniedException[] and javadoc:org.springframework.security.core.AuthenticationException[] into HTTP responses.
 
 `ExceptionTranslationFilter` is inserted into the <<servlet-filterchainproxy>> as one of the <<servlet-security-filters>>.
 
@@ -447,7 +447,7 @@ In Spring Security this is done by saving the `HttpServletRequest` using a <<req
 [[requestcache]]
 === RequestCache
 
-The `HttpServletRequest` is saved in the {security-api-url}org/springframework/security/web/savedrequest/RequestCache.html[`RequestCache`].
+The `HttpServletRequest` is saved in the javadoc:org.springframework.security.web.savedrequest.RequestCache[].
 When the user successfully authenticates, the `RequestCache` is used to replay the original request.
 The <<requestcacheawarefilter,`RequestCacheAwareFilter`>> uses the `RequestCache` to get the saved `HttpServletRequest` after the user authenticates, while the `ExceptionTranslationFilter` uses the `RequestCache` to save the `HttpServletRequest` after it detects `AuthenticationException`, before redirecting the user to the login endpoint.
 
@@ -463,7 +463,7 @@ There are a number of reasons you may want to not store the user's unauthenticat
 You may want to offload that storage onto the user's browser or store it in a database.
 Or you may want to shut off this feature since you always want to redirect the user to the home page instead of the page they tried to visit before login.
 
-To do that, you can use {security-api-url}org/springframework/security/web/savedrequest/NullRequestCache.html[the `NullRequestCache` implementation].
+To do that, you can use the javadoc:org.springframework.security.web.savedrequest.NullRequestCache[NullRequestCache] implementation.
 
 .Prevent the Request From Being Saved
 [tabs]
@@ -517,7 +517,7 @@ XML::
 [[requestcacheawarefilter]]
 === RequestCacheAwareFilter
 
-The {security-api-url}org/springframework/security/web/savedrequest/RequestCacheAwareFilter.html[`RequestCacheAwareFilter`] uses the <<requestcache,`RequestCache`>> to replay the original request.
+The javadoc:org.springframework.security.web.savedrequest.RequestCacheAwareFilter[] uses the <<requestcache,`RequestCache`>> to replay the original request.
 
 [[servlet-logging]]
 == Logging