Skip to content

Use javadoc-extension #1914

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Use javadoc-extension #1914

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
966d737
Improve generating document
ngocnhan-tran1996 Feb 21, 2025
c156ddb
Simplify version method
ngocnhan-tran1996 Feb 21, 2025
d457ff1
Polish
ngocnhan-tran1996 Feb 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/antora-playbook.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: ''
Expand Down
3 changes: 0 additions & 3 deletions docs/antora.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'
6 changes: 3 additions & 3 deletions docs/modules/ROOT/pages/core-model-components.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions docs/modules/ROOT/pages/getting-started.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
14 changes: 13 additions & 1 deletion docs/spring-authorization-server-docs.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(),
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this is correct?

I reviewed the changes in Spring Security spring-security#15386 and the gradle task syncAntoraAttachments was added which copies the javadoc as an asset to the site. I'm wondering if we need to do the same here?

@rwinch Is there a way to copy the Spring Security javadoc as an asset to the Spring Authorization Server site docs and reference it via a site asset? Or is this correct by directly referencing the Spring Security javadoc site?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rwinch As a side note, it appears syncAntoraAttachments is a required gradle task otherwise the antora build will fail saying it cannot find the javadoc resource. For example, after adding javadoc:org.springframework.security.oauth2.server.authorization.OAuth2AuthorizationCode[], the build will fail unless I add the syncAntoraAttachments task. However, this is not documented in Javadoc, unless I'm missing something?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we have the way copy the Spring Security javadoc to to the Spring Authorization Server, please let me know

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rwinch Is there a way to copy the Spring Security javadoc as an asset to the Spring Authorization Server site docs and reference it via a site asset?

You should copy Spring Authorization Servers javadoc to the Antora site, but you should NOT copy Spring Security's Javadoc.

The javadoc extension is just syntactic sugar for creating a link to Javadoc and can operate in a numerous different ways. It creates a link and does NOT create/copy Javadoc in the location it is pointing to.

Linking to Spring Authorization Server Javadoc

The default mode is to use xref:attachment$api/java which, as an xref to an attachment, will be validated by Antora that the link exists. This means you can get validation of the javadoc links existing for free. You will use this mode for linking to Spring Authorization Server javadoc. Since the javadoc extension is just creating a link, you still need to ensure that the Javadoc is added.

Spring Security configures the Antora Collector Extension to invoke the generateAntoraResources task (and in turn generateAntoraYml and syncAntoraAttachments). The generateAntoraYml task is how dynamic properties like version are set properly and synAntoraAttachments is how the Javadoc is generated/added as attachments to the site. Once it is added to the site, the Javadoc is automatically published as a part of your site.

Linking to Other Module's Javadoc

As for linking to other module's Javadoc (e.g. Spring Security), you should NOT copy it. Instead use Package Specific Locations or Link Specific Locations. You will notice that these demonstrate ways that external sites can be linked to. In this case it is more obvious, but worth pointing out that the javadoc extension does not publish the javadocs. It is just syntactic sugar for creating a link to something that must already exist.

'spring-boot-reference-base-url': "https://docs.spring.io/spring-boot/docs/${generateVersionWithoutPatch(springBootVersion)}/reference/html".toString()
]
}

Expand Down Expand Up @@ -76,3 +83,8 @@ dependencies {
tasks.named("test") {
useJUnitPlatform()
}

static String generateVersionWithoutPatch(String version) {

return version.split('\\.')[0, 1].join('.') + (version.endsWith('-SNAPSHOT') ? '-SNAPSHOT' : '')
}