Document @ClientRegistrationId on types

Issue gh-17806

Author: rwinch

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`
 

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
 

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() {
+}

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[]

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

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[]