io.swagger.v3.oas.annotations.Webhook does not work when defined on the method level. Fixes #2998

Author: bnasslahsen

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/service/OpenAPIService.java

@@ -26,6 +26,8 @@
 
 package org.springdoc.core.service;
 
+import java.lang.annotation.Annotation;
+import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -51,6 +53,7 @@
 import io.swagger.v3.core.util.AnnotationsUtils;
 import io.swagger.v3.oas.annotations.Hidden;
 import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.Webhook;
 import io.swagger.v3.oas.annotations.Webhooks;
 import io.swagger.v3.oas.annotations.security.SecuritySchemes;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -534,64 +537,96 @@ private Optional<OpenAPIDefinition> getOpenAPIDefinition() {
 		return Optional.ofNullable(apiDef);
 	}
 
+
 	/**
 	 * Get webhooks webhooks [ ].
 	 *
 	 * @return the webhooks [ ]
 	 */
 	public Webhooks[] getWebhooks() {
-		// List to collect all Webhooks annotations
 		List<Webhooks> allWebhooks = new ArrayList<>();
 
-		// Get beans with @Webhooks annotation managed by Spring
-		Map<String, Object> beansWithWebhooksAnnotation = context.getBeansWithAnnotation(Webhooks.class);
+		// First: scan Spring-managed beans
+		Map<String, Object> beans = context.getBeansWithAnnotation(Webhooks.class);
 
-		// Process Spring-managed beans
-		if (!beansWithWebhooksAnnotation.isEmpty()) {
-			beansWithWebhooksAnnotation.values().forEach(controller -> {
-				// Get the @Webhooks annotation(s) from each bean
-				Webhooks[] webhooksAnnotations = controller.getClass().getAnnotationsByType(Webhooks.class);
-				allWebhooks.addAll(Arrays.asList(webhooksAnnotations));
-			});
+		for (Object bean : beans.values()) {
+			Class<?> beanClass = bean.getClass();
+
+			// Collect @Webhooks or @Webhook on class level
+			collectWebhooksFromElement(beanClass, allWebhooks);
+
+			// Collect from methods
+			for (Method method : beanClass.getDeclaredMethods()) {
+				collectWebhooksFromElement(method, allWebhooks);
+			}
 		}
 
-		// If no beans with @Webhooks annotation found, perform classpath scanning
+		// Fallback: classpath scanning if nothing found
 		if (allWebhooks.isEmpty()) {
-			ClassPathScanningCandidateComponentProvider scanner = new ClassPathScanningCandidateComponentProvider(false);
+			ClassPathScanningCandidateComponentProvider scanner =
+					new ClassPathScanningCandidateComponentProvider(false);
 			scanner.addIncludeFilter(new AnnotationTypeFilter(Webhooks.class));
+			scanner.addIncludeFilter(new AnnotationTypeFilter(Webhook.class));
 
-			// Scan base packages if available
 			if (AutoConfigurationPackages.has(context)) {
-				List<String> packagesToScan = AutoConfigurationPackages.get(context);
+				for (String basePackage : AutoConfigurationPackages.get(context)) {
+					Set<BeanDefinition> candidates = scanner.findCandidateComponents(basePackage);
 
-				for (String basePackage : packagesToScan) {
-					// Perform the scan and get candidate components
-					Set<BeanDefinition> components = scanner.findCandidateComponents(basePackage);
-
-					// Loop through the components
-					for (BeanDefinition beanDefinition : components) {
+					for (BeanDefinition bd : candidates) {
 						try {
-							// Get the class name and load the class
-							String className = beanDefinition.getBeanClassName();
-							Class<?> clazz = Class.forName(className);
+							Class<?> clazz = Class.forName(bd.getBeanClassName());
+
+							// Class-level annotations
+							collectWebhooksFromElement(clazz, allWebhooks);
 
-							// Get @Webhooks annotation from the class
-							Webhooks[] webhooksAnnotations = clazz.getAnnotationsByType(Webhooks.class);
-							allWebhooks.addAll(Arrays.asList(webhooksAnnotations));
+							// Method-level annotations
+							for (Method method : clazz.getDeclaredMethods()) {
+								collectWebhooksFromElement(method, allWebhooks);
+							}
 
 						} catch (ClassNotFoundException e) {
-							// Log the error if the class is not found
 							LOGGER.error("Class not found in classpath: {}", e.getMessage());
 						}
 					}
 				}
 			}
 		}
 
-		// Convert the list of Webhooks annotations to an array and return
 		return allWebhooks.toArray(new Webhooks[0]);
 	}
 
+	/**
+	 * Collect webhooks from element.
+	 *
+	 * @param element   the element
+	 * @param collector the collector
+	 */
+	private void collectWebhooksFromElement(AnnotatedElement element, List<Webhooks> collector) {
+		// If @Webhooks is present (container)
+		Webhooks container = element.getAnnotation(Webhooks.class);
+		if (container != null) {
+			collector.add(container);
+		}
+
+		// If individual @Webhook annotations are present
+		Webhook[] individualWebhooks = element.getAnnotationsByType(Webhook.class);
+		if (individualWebhooks.length > 0) {
+			collector.add(new Webhooks() {
+				@Override
+				public Webhook[] value() {
+					return individualWebhooks;
+				}
+
+				@Override
+				public Class<? extends Annotation> annotationType() {
+					return Webhooks.class;
+				}
+			});
+		}
+	}
+
+
+
 	/**
 	 * Build open api with open api definition.
 	 *

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app9/WebHookResource.java

@@ -12,7 +12,7 @@
 
 @Webhooks({
 		@Webhook(
-				name = "newPet",
+				name = "newPet1",
 				operation = @Operation(
 						requestBody = @RequestBody(
 								description = "Information about a new pet in the system",
@@ -35,7 +35,38 @@
 		)
 })
 @Component
-public class WebHookResource {}
+public class WebHookResource {
+
+	@Webhook(
+			name = "newPet",
+			operation = @Operation(
+					requestBody = @RequestBody(
+							description = "Information about a new pet in the system",
+							content = {
+									@Content(
+											mediaType = "application/json",
+											schema = @Schema(
+													description = "Webhook Pet",
+													implementation = RequestDto.class
+											)
+									)
+							}
+					),
+					method = "post",
+					responses = @ApiResponse(
+							responseCode = "200",
+							description = "Return a 200 status to indicate that the data was received successfully"
+					)
+			)
+	)
+	public void newPet(RequestDto requestDto) {
+		// This method is intentionally left empty.
+		// The actual processing of the webhook data would be implemented here.
+		System.out.println("Received new pet with personal number: " + requestDto.getPersonalNumber());
+	}
+	
+	
+}
 
 
 class RequestDto {

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app9.json

@@ -24,6 +24,26 @@
     }
   },
   "webhooks": {
+    "newPet1": {
+      "post": {
+        "requestBody": {
+          "description": "Information about a new pet in the system",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RequestDto",
+                "description": "Webhook Pet"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Return a 200 status to indicate that the data was received successfully"
+          }
+        }
+      }
+    },
     "newPet": {
       "post": {
         "requestBody": {