From a0fe04c4aa3741b4b03c6b70ca66232a1aa61da3 Mon Sep 17 00:00:00 2001 From: Rob Winch <362503+rwinch@users.noreply.github.com> Date: Fri, 12 Sep 2025 15:04:44 -0500 Subject: [PATCH] Document @ClientRegistrationId on types Issue gh-17806 --- .../integrations/rest/http-interface.adoc | 7 ++++ docs/modules/ROOT/pages/whats-new.adoc | 2 +- .../integrations/rest/type/Hovercard.java | 25 +++++++++++ .../integrations/rest/type/UserService.java | 41 +++++++++++++++++++ .../integrations/rest/type/Hovercard.kt | 24 +++++++++++ .../integrations/rest/type/UserService.kt | 39 ++++++++++++++++++ 6 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 docs/src/test/java/org/springframework/security/docs/features/integrations/rest/type/Hovercard.java create mode 100644 docs/src/test/java/org/springframework/security/docs/features/integrations/rest/type/UserService.java create mode 100644 docs/src/test/kotlin/org/springframework/security/kt/docs/features/integrations/rest/type/Hovercard.kt create mode 100644 docs/src/test/kotlin/org/springframework/security/kt/docs/features/integrations/rest/type/UserService.kt diff --git a/docs/modules/ROOT/pages/features/integrations/rest/http-interface.adoc b/docs/modules/ROOT/pages/features/integrations/rest/http-interface.adoc index 1d818f520b..3ee8ef1520 100644 --- a/docs/modules/ROOT/pages/features/integrations/rest/http-interface.adoc +++ b/docs/modules/ROOT/pages/features/integrations/rest/http-interface.adoc @@ -51,6 +51,13 @@ include-code::./UserService[tag=getAuthenticatedUser] The xref:features/integrations/rest/http-interface.adoc#client-registration-id[`@ClientRegistrationId`] will be processed by xref:features/integrations/rest/http-interface.adoc#client-registration-id-processor[`ClientRegistrationIdProcessor`] +[[type]] +=== Type Level Declarations + +`@ClientRegistrationId` can also be added at the type level to avoid repeating the declaration on every method. + +include-code::./UserService[tag=type] + [[client-registration-id-processor]] == `ClientRegistrationIdProcessor` diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc index a613e8fbec..2955ebb821 100644 --- a/docs/modules/ROOT/pages/whats-new.adoc +++ b/docs/modules/ROOT/pages/whats-new.adoc @@ -49,7 +49,7 @@ http.csrf((csrf) -> csrf.spa()); * Added OAuth2 Support for xref:features/integrations/rest/http-interface.adoc[HTTP Interface Integration] * Added support for custom `JwkSource` in `NimbusJwtDecoder`, allowing usage of Nimbus's `JwkSourceBuilder` API * Added builder for `NimbusJwtEncoder`, supports specifying an EC or RSA key pair or a secret key -* Added support for `@ClientRegistrationId` at class level, eliminating the need for method level repetition +* Added support for `@ClientRegistrationId` at the xref:features/integrations/rest/http-interface.adoc#type[type level], eliminating the need for method level repetition == SAML 2.0 diff --git a/docs/src/test/java/org/springframework/security/docs/features/integrations/rest/type/Hovercard.java b/docs/src/test/java/org/springframework/security/docs/features/integrations/rest/type/Hovercard.java new file mode 100644 index 0000000000..32dae93ced --- /dev/null +++ b/docs/src/test/java/org/springframework/security/docs/features/integrations/rest/type/Hovercard.java @@ -0,0 +1,25 @@ +/* + * Copyright 2004-present the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.security.docs.features.integrations.rest.type; + +/** + * Used to ensure {@link UserService} compiles, but not show in the documentation. + * + * @author Rob Winch + */ +public record Hovercard() { +} diff --git a/docs/src/test/java/org/springframework/security/docs/features/integrations/rest/type/UserService.java b/docs/src/test/java/org/springframework/security/docs/features/integrations/rest/type/UserService.java new file mode 100644 index 0000000000..7b0e527e1d --- /dev/null +++ b/docs/src/test/java/org/springframework/security/docs/features/integrations/rest/type/UserService.java @@ -0,0 +1,41 @@ +/* + * Copyright 2004-present the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain clients copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.security.docs.features.integrations.rest.type; + +import org.springframework.security.docs.features.integrations.rest.clientregistrationid.User; +import org.springframework.security.oauth2.client.annotation.ClientRegistrationId; +import org.springframework.web.bind.annotation.PathVariable; +import org.springframework.web.service.annotation.GetExchange; +import org.springframework.web.service.annotation.HttpExchange; + +/** + * Demonstrates a service for {@link ClientRegistrationId} at the type level. + * @author Rob Winch + */ +// tag::type[] +@HttpExchange +@ClientRegistrationId("github") +public interface UserService { + + @GetExchange("/user") + User getAuthenticatedUser(); + + @GetExchange("/users/{username}/hovercard") + Hovercard getHovercard(@PathVariable String username); + +} +// end::type[] diff --git a/docs/src/test/kotlin/org/springframework/security/kt/docs/features/integrations/rest/type/Hovercard.kt b/docs/src/test/kotlin/org/springframework/security/kt/docs/features/integrations/rest/type/Hovercard.kt new file mode 100644 index 0000000000..e4af07ffd2 --- /dev/null +++ b/docs/src/test/kotlin/org/springframework/security/kt/docs/features/integrations/rest/type/Hovercard.kt @@ -0,0 +1,24 @@ +/* + * Copyright 2004-present the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.security.kt.docs.features.integrations.rest.type + +/** + * Used to ensure [UserService] compiles, but not show in the documentation. + * + * @author Rob Winch + */ +class Hovercard diff --git a/docs/src/test/kotlin/org/springframework/security/kt/docs/features/integrations/rest/type/UserService.kt b/docs/src/test/kotlin/org/springframework/security/kt/docs/features/integrations/rest/type/UserService.kt new file mode 100644 index 0000000000..531a8a50e7 --- /dev/null +++ b/docs/src/test/kotlin/org/springframework/security/kt/docs/features/integrations/rest/type/UserService.kt @@ -0,0 +1,39 @@ +/* + * Copyright 2004-present the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain clients copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.security.kt.docs.features.integrations.rest.type + +import org.springframework.security.kt.docs.features.integrations.rest.clientregistrationid.User +import org.springframework.security.oauth2.client.annotation.ClientRegistrationId +import org.springframework.web.bind.annotation.PathVariable +import org.springframework.web.service.annotation.GetExchange +import org.springframework.web.service.annotation.HttpExchange + +/** + * Demonstrates a service for [ClientRegistrationId] at the type level. + * @author Rob Winch + */ +// tag::type[] +@HttpExchange +@ClientRegistrationId("github") +interface UserService { + @GetExchange("/user") + fun getAuthenticatedUser(): User + + @GetExchange("/users/{username}/hovercard") + fun getHovercard(@PathVariable username: String): Hovercard +} +// end::type[]