Support OpenAPI 3.1 top-level webhooks (#375)

OpenAPI 3.1 adds a top-level `webhooks` object: a map of named Path Item
Objects describing out-of-band requests. The generator only iterated
`paths`, so webhooks were ignored - no handler interface, no payload models.

Add OpenApiUtil.mergeWebhooksIntoPaths, invoked right after parsing in
OpenApiGenerator.processFile. Each webhook (keyed by name) is merged into
`paths` under a "/"-prefixed key so the existing pipeline generates a
handler interface for its operations and the request/response payload
models. `paths` is created if the contract has none, and existing `paths`
entries are never overwritten.

Adds a 3.1.0 webhooks-only regression fixture (testWebhooks) with golden
assets (NewPetApi + PetDTO).

Stacked on the 6.4.0 array-type work (#376); both are part of the 3.1
support milestone, so the version stays 6.4.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: joseegarcia

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/openapi/OpenApiGenerator.java

@@ -98,6 +98,7 @@ private void processPackage(final String apiPackage) {
   private void processFile(final SpecFile specFile) {
 
     final JsonNode openAPI = OpenApiUtil.getPojoFromSpecFile(baseDir, specFile);
+    OpenApiUtil.mergeWebhooksIntoPaths(openAPI);
     final String clientPackage = specFile.getClientPackage();
 
     if (specFile.isCallMode()) {

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/openapi/utils/OpenApiUtil.java

@@ -34,6 +34,8 @@ public class OpenApiUtil {
 
   public static final String PATHS = "paths";
 
+  public static final String WEBHOOKS = "webhooks";
+
   static final Set<String> REST_VERB_SET = Set.of("get", "post", "delete", "patch", "put");
 
   private OpenApiUtil() {
@@ -91,6 +93,31 @@ public static JsonNode getPojoFromSpecFile(final Path baseDir, final SpecFile sp
     return SchemaUtil.getPojoFromRef(baseDir.toUri(), specFile.getFilePath());
   }
 
+  /**
+   * Merges the OpenAPI 3.1 top-level {@code webhooks} object into {@code paths} so the existing
+   * path pipeline generates a handler interface and the request/response payload models for each
+   * webhook. Each webhook is a Path Item Object keyed by name; it is added under a {@code "/"}-
+   * prefixed key (webhooks have no URL) so the by-url grouping treats the webhook name as the
+   * endpoint. Existing {@code paths} entries take precedence and are never overwritten.
+   *
+   * @param openApi the parsed root contract; its {@code paths} node is created/extended in place.
+   */
+  public static void mergeWebhooksIntoPaths(final JsonNode openApi) {
+    final JsonNode webhooks = openApi.get(WEBHOOKS);
+    if (webhooks instanceof ObjectNode && openApi instanceof ObjectNode) {
+      final ObjectNode root = (ObjectNode) openApi;
+      final ObjectNode paths = root.has(PATHS) && root.get(PATHS).isObject()
+          ? (ObjectNode) root.get(PATHS)
+          : root.putObject(PATHS);
+      webhooks.fields().forEachRemaining(webhook -> {
+        final String pathKey = webhook.getKey().startsWith("/") ? webhook.getKey() : "/" + webhook.getKey();
+        if (!paths.has(pathKey)) {
+          paths.set(pathKey, webhook.getValue());
+        }
+      });
+    }
+  }
+
   public static Map<String, JsonNode> processPaths(final JsonNode openApi, final Map<String, JsonNode> schemaMap, SpecFile specFile) {
     final var basicJsonNodeMap = new HashMap<>(schemaMap);
 

multiapi-engine/src/test/java/com/sngular/api/generator/plugin/openapi/OpenApiGeneratorFixtures.java

@@ -147,6 +147,13 @@ public final class OpenApiGeneratorFixtures {
 					.clientPackage("com.sngular.multifileplugin.externalref.client").modelNamePrefix("Api")
 					.modelNameSuffix("DTO").build());
 
+	static final List<SpecFile> TEST_WEBHOOKS = List
+			.of(SpecFile.builder().filePath("openapigenerator/testWebhooks/api-test.yml")
+					.apiPackage("com.sngular.multifileplugin.webhooks")
+					.modelPackage("com.sngular.multifileplugin.webhooks.model")
+					.clientPackage("com.sngular.multifileplugin.webhooks.client")
+					.modelNameSuffix("DTO").build());
+
 	static final List<SpecFile> TEST_OPEN_API_31_TYPES = List
 			.of(SpecFile.builder().filePath("openapigenerator/testOpenApi31Types/api-test.yml")
 					.apiPackage("com.sngular.multifileplugin.openapi31types")
@@ -770,6 +777,24 @@ static Function<Path, Boolean> validateExternalRefGeneration() {
 				DEFAULT_MODEL_API, expectedExceptionFiles, DEFAULT_EXCEPTION_API);
 	}
 
+	static Function<Path, Boolean> validateWebhooks() {
+
+		final String DEFAULT_TARGET_API = "generated/com/sngular/multifileplugin/webhooks";
+
+		final String DEFAULT_MODEL_API = "generated/com/sngular/multifileplugin/webhooks/model";
+
+		final String COMMON_PATH = "openapigenerator/testWebhooks/";
+
+		final String ASSETS_PATH = COMMON_PATH + "assets/";
+
+		final List<String> expectedTestApiFile = List.of(ASSETS_PATH + "NewPetApi.java");
+
+		final List<String> expectedTestApiModelFiles = List.of(ASSETS_PATH + "PetDTO.java");
+
+		return path -> commonTest(path, expectedTestApiFile, expectedTestApiModelFiles, DEFAULT_TARGET_API,
+				DEFAULT_MODEL_API, Collections.emptyList(), null);
+	}
+
 	static Function<Path, Boolean> validateOpenApi31Types() {
 
 		final String DEFAULT_TARGET_API = "generated/com/sngular/multifileplugin/openapi31types";

multiapi-engine/src/test/java/com/sngular/api/generator/plugin/openapi/OpenApiGeneratorTest.java

@@ -85,6 +85,8 @@ static Stream<Arguments> fileSpecToProcess() {
             OpenApiGeneratorFixtures.validateExternalRefGeneration()),
         Arguments.of("testOpenApi31Types", OpenApiGeneratorFixtures.TEST_OPEN_API_31_TYPES,
             OpenApiGeneratorFixtures.validateOpenApi31Types()),
+        Arguments.of("testWebhooks", OpenApiGeneratorFixtures.TEST_WEBHOOKS,
+            OpenApiGeneratorFixtures.validateWebhooks()),
         Arguments.of("testAnyOfInResponse", OpenApiGeneratorFixtures.TEST_ANY_OF_IN_RESPONSE,
             OpenApiGeneratorFixtures.validateAnyOfInResponse()),
         Arguments.of("testOneOfInResponse", OpenApiGeneratorFixtures.TEST_ONE_OF_IN_RESPONSE,

multiapi-engine/src/test/resources/openapigenerator/testWebhooks/api-test.yml

@@ -0,0 +1,40 @@
+---
+# Regression for OpenAPI 3.1 top-level `webhooks` support (issue #375).
+# A webhooks-only contract (no `paths`): each webhook is a Path Item Object keyed by
+# name. The generator merges these into the path pipeline so a handler interface and the
+# request payload model are generated.
+openapi: "3.1.0"
+info:
+  version: 1.0.0
+  title: Webhooks API (OpenAPI 3.1)
+  license:
+    name: MIT
+servers:
+  - url: http://localhost:8080/v1
+tags:
+  - name: webhook
+webhooks:
+  newPet:
+    post:
+      summary: New pet notification
+      operationId: newPetWebhook
+      tags:
+        - webhook
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Pet"
+      responses:
+        '200':
+          description: Notification acknowledged
+components:
+  schemas:
+    Pet:
+      type: object
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string

multiapi-engine/src/test/resources/openapigenerator/testWebhooks/assets/NewPetApi.java

@@ -0,0 +1,47 @@
+package com.sngular.multifileplugin.webhooks;
+
+import java.util.Optional;
+import java.util.List;
+import java.util.Map;
+import javax.validation.Valid;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import org.springframework.http.MediaType;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.context.request.NativeWebRequest;
+
+import com.sngular.multifileplugin.webhooks.model.PetDTO;
+
+public interface NewPetApi {
+
+  /**
+   * POST /newPet: New pet notification
+   * @param petDTO
+   * @return  Notification acknowledged; (status code 200)
+   */
+
+  @Operation(
+    operationId = "newPetWebhook",
+    summary = "New pet notification",
+    tags = {"webhook"},
+    responses = {
+      @ApiResponse(responseCode = "200", description = "Notification acknowledged")
+    }
+  )
+  @RequestMapping(
+    method = RequestMethod.POST,
+    value = "/newPet",
+    produces = {"application/json"}
+  )
+
+  default ResponseEntity<Void> newPetWebhook(@Parameter(name = "petDTO", description = "", required = false, schema = @Schema(description = "")) @Valid @RequestBody PetDTO petDTO) {
+    return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
+  }
+
+}

multiapi-engine/src/test/resources/openapigenerator/testWebhooks/assets/PetDTO.java

@@ -0,0 +1,94 @@
+package com.sngular.multifileplugin.webhooks.model;
+
+import java.util.Objects;
+
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonPOJOBuilder;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@JsonDeserialize(builder = PetDTO.PetDTOBuilder.class)
+public class PetDTO {
+
+  @JsonProperty(value ="name")
+  private String name;
+  @JsonProperty(value ="id")
+  private Long id;
+
+  private PetDTO(PetDTOBuilder builder) {
+    this.name = builder.name;
+    this.id = builder.id;
+
+  }
+
+  public static PetDTO.PetDTOBuilder builder() {
+    return new PetDTO.PetDTOBuilder();
+  }
+
+  @JsonPOJOBuilder(buildMethodName = "build", withPrefix = "")
+  public static class PetDTOBuilder {
+
+    private String name;
+    private Long id;
+
+    public PetDTO.PetDTOBuilder name(String name) {
+      this.name = name;
+      return this;
+    }
+
+    public PetDTO.PetDTOBuilder id(Long id) {
+      this.id = id;
+      return this;
+    }
+
+    public PetDTO build() {
+      PetDTO petDTO = new PetDTO(this);
+      return petDTO;
+    }
+  }
+
+  @Schema(name = "name", required = false)
+  public String getName() {
+    return name;
+  }
+  public void setName(String name) {
+    this.name = name;
+  }
+
+  @Schema(name = "id", required = false)
+  public Long getId() {
+    return id;
+  }
+  public void setId(Long id) {
+    this.id = id;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
+    PetDTO petDTO = (PetDTO) o;
+    return Objects.equals(this.name, petDTO.name) && Objects.equals(this.id, petDTO.id);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(name, id);
+  }
+
+  @Override
+  public String toString() {
+    StringBuilder sb = new StringBuilder();
+    sb.append("PetDTO{");
+    sb.append(" name:").append(name).append(",");
+    sb.append(" id:").append(id);
+    sb.append("}");
+    return sb.toString();
+  }
+
+
+}