From 966d7379736ecd574121a2de5c18fb7675f9a4d3 Mon Sep 17 00:00:00 2001 From: Tran Ngoc Nhan Date: Fri, 21 Feb 2025 18:04:38 +0700 Subject: [PATCH 1/3] Improve generating document Signed-off-by: Tran Ngoc Nhan --- docs/antora-playbook.yml | 1 + docs/antora.yml | 3 --- .../ROOT/pages/core-model-components.adoc | 6 ++--- docs/modules/ROOT/pages/getting-started.adoc | 4 ++-- docs/spring-authorization-server-docs.gradle | 22 ++++++++++++++++++- 5 files changed, 27 insertions(+), 9 deletions(-) diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml index a355b173f..1f4bdf8e2 100644 --- a/docs/antora-playbook.yml +++ b/docs/antora-playbook.yml @@ -25,6 +25,7 @@ asciidoc: extensions: - '@asciidoctor/tabs' - '@springio/asciidoctor-extensions' + - '@springio/asciidoctor-extensions/javadoc-extension' urls: latest_version_segment_strategy: redirect:to latest_version_segment: '' diff --git a/docs/antora.yml b/docs/antora.yml index f1d1424ba..7c3731373 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -15,9 +15,6 @@ asciidoc: attributes: attribute-missing: 'warn' chomp: 'all' - spring-security-reference-base-url: "https://docs.spring.io/spring-security/reference" - spring-security-api-base-url: "https://docs.spring.io/spring-security/site/docs/current/api" - spring-boot-reference-base-url: "https://docs.spring.io/spring-boot/docs/current/reference/html" examples-dir: example$docs-src samples-dir: example$samples docs-java: '{examples-dir}/main/java' diff --git a/docs/modules/ROOT/pages/core-model-components.adoc b/docs/modules/ROOT/pages/core-model-components.adoc index 03032ce43..613ba4a30 100644 --- a/docs/modules/ROOT/pages/core-model-components.adoc +++ b/docs/modules/ROOT/pages/core-model-components.adoc @@ -148,13 +148,13 @@ An `OAuth2Authorization` is a representation of an OAuth2 authorization, which h [TIP] The corresponding authorization model in Spring Security's OAuth2 Client support is {spring-security-reference-base-url}/servlet/oauth2/client/core.html#oauth2Client-authorized-client[OAuth2AuthorizedClient]. -After the successful completion of an authorization grant flow, an `OAuth2Authorization` is created and associates an {spring-security-api-base-url}/org/springframework/security/oauth2/core/OAuth2AccessToken.html[`OAuth2AccessToken`], an (optional) {spring-security-api-base-url}/org/springframework/security/oauth2/core/OAuth2RefreshToken.html[`OAuth2RefreshToken`], and additional state specific to the executed authorization grant type. +After the successful completion of an authorization grant flow, an `OAuth2Authorization` is created and associates an javadoc:org.springframework.security.oauth2.core.OAuth2AccessToken[], an (optional) javadoc:org.springframework.security.oauth2.core.OAuth2RefreshToken[], and additional state specific to the executed authorization grant type. -The {spring-security-api-base-url}/org/springframework/security/oauth2/core/OAuth2Token.html[`OAuth2Token`] instances associated with an `OAuth2Authorization` vary, depending on the authorization grant type. +The javadoc:org.springframework.security.oauth2.core.OAuth2Token[] instances associated with an `OAuth2Authorization` vary, depending on the authorization grant type. For the OAuth2 https://datatracker.ietf.org/doc/html/rfc6749#section-4.1[authorization_code grant], an `OAuth2AuthorizationCode`, an `OAuth2AccessToken`, and an (optional) `OAuth2RefreshToken` are associated. -For the OpenID Connect 1.0 https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[authorization_code grant], an `OAuth2AuthorizationCode`, an {spring-security-api-base-url}/org/springframework/security/oauth2/core/oidc/OidcIdToken.html[`OidcIdToken`], an `OAuth2AccessToken`, and an (optional) `OAuth2RefreshToken` are associated. +For the OpenID Connect 1.0 https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[authorization_code grant], an `OAuth2AuthorizationCode`, an javadoc:org.springframework.security.oauth2.core.oidc.OidcIdToken[], an `OAuth2AccessToken`, and an (optional) `OAuth2RefreshToken` are associated. For the OAuth2 https://datatracker.ietf.org/doc/html/rfc6749#section-4.4[client_credentials grant], only an `OAuth2AccessToken` is associated. diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc index 4f7ae90f4..47ba72f18 100644 --- a/docs/modules/ROOT/pages/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -99,9 +99,9 @@ This is a minimal configuration for getting started quickly. To understand what <1> A Spring Security filter chain for the xref:protocol-endpoints.adoc[Protocol Endpoints]. <2> A Spring Security filter chain for https://docs.spring.io/spring-security/reference/servlet/authentication/index.html[authentication]. -<3> An instance of {spring-security-api-base-url}/org/springframework/security/core/userdetails/UserDetailsService.html[`UserDetailsService`] for retrieving users to authenticate. +<3> An instance of javadoc:org.springframework.security.core.userdetails.UserDetailsService[] for retrieving users to authenticate. <4> An instance of xref:core-model-components.adoc#registered-client-repository[`RegisteredClientRepository`] for managing clients. <5> An instance of `com.nimbusds.jose.jwk.source.JWKSource` for signing access tokens. <6> An instance of `java.security.KeyPair` with keys generated on startup used to create the `JWKSource` above. -<7> An instance of {spring-security-api-base-url}/org/springframework/security/oauth2/jwt/JwtDecoder.html[`JwtDecoder`] for decoding signed access tokens. +<7> An instance of javadoc:org.springframework.security.oauth2.jwt.JwtDecoder[] for decoding signed access tokens. <8> An instance of xref:configuration-model#configuring-authorization-server-settings[`AuthorizationServerSettings`] to configure Spring Authorization Server. diff --git a/docs/spring-authorization-server-docs.gradle b/docs/spring-authorization-server-docs.gradle index 9b6a80dbe..51107df66 100644 --- a/docs/spring-authorization-server-docs.gradle +++ b/docs/spring-authorization-server-docs.gradle @@ -30,8 +30,15 @@ tasks.named("generateAntoraYml") { def generateAttributes() { + def springBootVersion = project.configurations.named("implementation").get() + .dependencies.find {it -> ("spring-boot-dependencies" == it.name) } + .version + String springSecurityVersion = libs.org.springframework.security.spring.security.bom.get().versionConstraint.displayName return [ - "spring-authorization-server-version": project.version + "spring-authorization-server-version": project.version, + "spring-security-reference-base-url": "https://docs.spring.io/spring-security/reference/${generateVersionWithoutPatch(springSecurityVersion)}".toString(), + "javadoc-location-org-springframework-security": "https://docs.spring.io/spring-security/site/docs/$springSecurityVersion/api".toString(), + "spring-boot-reference-base-url": "https://docs.spring.io/spring-boot/docs/${generateVersionWithoutPatch(springBootVersion)}/reference/html".toString() ] } @@ -76,3 +83,16 @@ dependencies { tasks.named("test") { useJUnitPlatform() } + +static String generateVersionWithoutPatch(String version) { + + def matcher = version =~ /^(\d+.\d+).\d+(-SNAPSHOT|-M\d+)?$/ + if(matcher) { + + return matcher[0][2] == null || matcher[0][2].startsWith("-M") + ? matcher[0][1] + : matcher[0][1] + matcher[0][2] + } + + return version +} From c156ddbe66a0c825996f9cb44e9b3acdd553bbd7 Mon Sep 17 00:00:00 2001 From: Tran Ngoc Nhan Date: Fri, 21 Feb 2025 23:39:17 +0700 Subject: [PATCH 2/3] Simplify version method Signed-off-by: Tran Ngoc Nhan --- docs/spring-authorization-server-docs.gradle | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/spring-authorization-server-docs.gradle b/docs/spring-authorization-server-docs.gradle index 51107df66..4f43fd03b 100644 --- a/docs/spring-authorization-server-docs.gradle +++ b/docs/spring-authorization-server-docs.gradle @@ -86,13 +86,5 @@ tasks.named("test") { static String generateVersionWithoutPatch(String version) { - def matcher = version =~ /^(\d+.\d+).\d+(-SNAPSHOT|-M\d+)?$/ - if(matcher) { - - return matcher[0][2] == null || matcher[0][2].startsWith("-M") - ? matcher[0][1] - : matcher[0][1] + matcher[0][2] - } - - return version + return version.split('\\.')[0, 1].join('.') + (version.endsWith('-SNAPSHOT') ? '-SNAPSHOT' : '') } From d457ff1c1b1396b22150d0f64394658716251ab5 Mon Sep 17 00:00:00 2001 From: Tran Ngoc Nhan Date: Fri, 21 Feb 2025 23:45:51 +0700 Subject: [PATCH 3/3] Polish Signed-off-by: Tran Ngoc Nhan --- docs/spring-authorization-server-docs.gradle | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/spring-authorization-server-docs.gradle b/docs/spring-authorization-server-docs.gradle index 4f43fd03b..c0acac378 100644 --- a/docs/spring-authorization-server-docs.gradle +++ b/docs/spring-authorization-server-docs.gradle @@ -35,10 +35,10 @@ def generateAttributes() { .version String springSecurityVersion = libs.org.springframework.security.spring.security.bom.get().versionConstraint.displayName return [ - "spring-authorization-server-version": project.version, - "spring-security-reference-base-url": "https://docs.spring.io/spring-security/reference/${generateVersionWithoutPatch(springSecurityVersion)}".toString(), - "javadoc-location-org-springframework-security": "https://docs.spring.io/spring-security/site/docs/$springSecurityVersion/api".toString(), - "spring-boot-reference-base-url": "https://docs.spring.io/spring-boot/docs/${generateVersionWithoutPatch(springBootVersion)}/reference/html".toString() + 'spring-authorization-server-version': project.version, + 'spring-security-reference-base-url': "https://docs.spring.io/spring-security/reference/${generateVersionWithoutPatch(springSecurityVersion)}".toString(), + 'javadoc-location-org-springframework-security': "https://docs.spring.io/spring-security/site/docs/$springSecurityVersion/api".toString(), + 'spring-boot-reference-base-url': "https://docs.spring.io/spring-boot/docs/${generateVersionWithoutPatch(springBootVersion)}/reference/html".toString() ] }