Merge branch 'main' into feat/375-openapi-3.1-support

Author: jemacineiras

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.solvePathRefs(openAPI, baseDir.resolve(specFile.getFilePath()).getParent().toUri());
     final String clientPackage = specFile.getClientPackage();
 
     if (specFile.isCallMode()) {

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

@@ -6,6 +6,7 @@
 
 package com.sngular.api.generator.plugin.openapi.utils;
 
+import java.net.URI;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -91,6 +92,33 @@ public static JsonNode getPojoFromSpecFile(final Path baseDir, final SpecFile sp
     return SchemaUtil.getPojoFromRef(baseDir.toUri(), specFile.getFilePath());
   }
 
+  /**
+   * Dereferences Path Item Objects that are declared as a {@code $ref} to another file (modular
+   * contracts). These references are otherwise never resolved, so the affected paths silently
+   * disappear from generation. The referenced Path Item is resolved and set in place, so every
+   * downstream consumer (API grouping, path mapping and model extraction) sees the real operations.
+   *
+   * @param openApi      the parsed root contract; its {@code paths} node is mutated in place.
+   * @param rootFilePath base URI used to resolve relative external references.
+   */
+  public static void solvePathRefs(final JsonNode openApi, final URI rootFilePath) {
+    final JsonNode pathsNode = openApi.get(PATHS);
+    if (pathsNode instanceof ObjectNode) {
+      final ObjectNode paths = (ObjectNode) pathsNode;
+      final Map<String, JsonNode> resolvedItems = new HashMap<>();
+      paths.fields().forEachRemaining(pathItem -> {
+        final JsonNode pathValue = pathItem.getValue();
+        if (ApiTool.hasRef(pathValue)) {
+          final JsonNode resolved = SchemaUtil.solveRef(ApiTool.getRefValue(pathValue), new HashMap<>(), rootFilePath);
+          if (Objects.nonNull(resolved)) {
+            resolvedItems.put(pathItem.getKey(), resolved);
+          }
+        }
+      });
+      resolvedItems.forEach(paths::set);
+    }
+  }
+
   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

@@ -152,6 +152,13 @@ public final class OpenApiGeneratorFixtures {
 					.apiPackage("com.sngular.multifileplugin.openapi31types")
 					.modelPackage("com.sngular.multifileplugin.openapi31types.model")
 					.clientPackage("com.sngular.multifileplugin.openapi31types.client")
+          .modelNameSuffix("DTO").build());
+
+	static final List<SpecFile> TEST_EXTERNAL_PATH_ITEM_REF_GENERATION = List
+			.of(SpecFile.builder().filePath("openapigenerator/testExternalPathItemRefsGeneration/api-test.yml")
+					.apiPackage("com.sngular.multifileplugin.externalpathitemref")
+					.modelPackage("com.sngular.multifileplugin.externalpathitemref.model")
+					.clientPackage("com.sngular.multifileplugin.externalpathitemref.client")
 					.modelNameSuffix("DTO").build());
 
 	static final List<SpecFile> TEST_ANY_OF_IN_RESPONSE = List
@@ -784,6 +791,24 @@ static Function<Path, Boolean> validateOpenApi31Types() {
 
 		final List<String> expectedTestApiModelFiles = List.of(ASSETS_PATH + "ProfileDTO.java");
 
+    return path -> commonTest(path, expectedTestApiFile, expectedTestApiModelFiles, DEFAULT_TARGET_API,
+    DEFAULT_MODEL_API, Collections.emptyList(), null);
+	}
+  
+	static Function<Path, Boolean> validateExternalPathItemRefGeneration() {
+
+		final String DEFAULT_TARGET_API = "generated/com/sngular/multifileplugin/externalpathitemref";
+
+		final String DEFAULT_MODEL_API = "generated/com/sngular/multifileplugin/externalpathitemref/model";
+
+		final String COMMON_PATH = "openapigenerator/testExternalPathItemRefsGeneration/";
+
+		final String ASSETS_PATH = COMMON_PATH + "assets/";
+
+		final List<String> expectedTestApiFile = List.of(ASSETS_PATH + "DashboardApi.java");
+
+		final List<String> expectedTestApiModelFiles = List.of(ASSETS_PATH + "DashboardDTO.java");
+
 		return path -> commonTest(path, expectedTestApiFile, expectedTestApiModelFiles, DEFAULT_TARGET_API,
 				DEFAULT_MODEL_API, Collections.emptyList(), null);
 	}

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("testExternalPathItemRefsGeneration", OpenApiGeneratorFixtures.TEST_EXTERNAL_PATH_ITEM_REF_GENERATION,
+            OpenApiGeneratorFixtures.validateExternalPathItemRefGeneration()),
         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/testExternalPathItemRefsGeneration/api-test.yml

@@ -0,0 +1,32 @@
+---
+# Reproduction for: external Path Item $ref produces 0 files silently (issue #372).
+# The `paths` entries are $ref'd out to a separate file (modular contract), exactly
+# like a Redocly/Swagger split contract. openapi 3.1.0 to match the real-world case,
+# but no 3.1-only schema constructs are used so the ONLY blocker under test is the
+# unresolved external Path Item $ref. Schemas are referenced with the already-supported
+# internal component ref style (#/components/schemas/...).
+openapi: "3.1.0"
+info:
+  version: 1.0.0
+  title: Dashboard API (modular contract)
+  license:
+    name: MIT
+servers:
+  - url: http://localhost:8080/v1
+tags:
+  - name: dashboard
+paths:
+  /dashboard:
+    $ref: "./paths/dashboard.yml"
+components:
+  schemas:
+    Dashboard:
+      type: object
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        widgetCount:
+          type: integer
+          format: int32

multiapi-engine/src/test/resources/openapigenerator/testExternalPathItemRefsGeneration/assets/DashboardApi.java

@@ -0,0 +1,46 @@
+package com.sngular.multifileplugin.externalpathitemref;
+
+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.externalpathitemref.model.DashboardDTO;
+
+public interface DashboardApi {
+
+  /**
+   * GET /dashboard: Get the dashboard
+   * @return  The requested dashboard; (status code 200)
+   */
+
+  @Operation(
+    operationId = "getDashboard",
+    summary = "Get the dashboard",
+    tags = {"dashboard"},
+    responses = {
+      @ApiResponse(responseCode = "200", description = "The requested dashboard", content = @Content(mediaType = "application/json", schema = @Schema(implementation = DashboardDTO.class)))
+    }
+  )
+  @RequestMapping(
+    method = RequestMethod.GET,
+    value = "/dashboard",
+    produces = {"application/json"}
+  )
+
+  default ResponseEntity<DashboardDTO> getDashboard() {
+    return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
+  }
+
+}

multiapi-engine/src/test/resources/openapigenerator/testExternalPathItemRefsGeneration/assets/DashboardDTO.java

@@ -0,0 +1,112 @@
+package com.sngular.multifileplugin.externalpathitemref.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 = DashboardDTO.DashboardDTOBuilder.class)
+public class DashboardDTO {
+
+  @JsonProperty(value ="id")
+  private String id;
+  @JsonProperty(value ="title")
+  private String title;
+  @JsonProperty(value ="widgetCount")
+  private Integer widgetCount;
+
+  private DashboardDTO(DashboardDTOBuilder builder) {
+    this.id = builder.id;
+    this.title = builder.title;
+    this.widgetCount = builder.widgetCount;
+
+  }
+
+  public static DashboardDTO.DashboardDTOBuilder builder() {
+    return new DashboardDTO.DashboardDTOBuilder();
+  }
+
+  @JsonPOJOBuilder(buildMethodName = "build", withPrefix = "")
+  public static class DashboardDTOBuilder {
+
+    private String id;
+    private String title;
+    private Integer widgetCount;
+
+    public DashboardDTO.DashboardDTOBuilder id(String id) {
+      this.id = id;
+      return this;
+    }
+
+    public DashboardDTO.DashboardDTOBuilder title(String title) {
+      this.title = title;
+      return this;
+    }
+
+    public DashboardDTO.DashboardDTOBuilder widgetCount(Integer widgetCount) {
+      this.widgetCount = widgetCount;
+      return this;
+    }
+
+    public DashboardDTO build() {
+      DashboardDTO dashboardDTO = new DashboardDTO(this);
+      return dashboardDTO;
+    }
+  }
+
+  @Schema(name = "id", required = false)
+  public String getId() {
+    return id;
+  }
+  public void setId(String id) {
+    this.id = id;
+  }
+
+  @Schema(name = "title", required = false)
+  public String getTitle() {
+    return title;
+  }
+  public void setTitle(String title) {
+    this.title = title;
+  }
+
+  @Schema(name = "widgetCount", required = false)
+  public Integer getWidgetCount() {
+    return widgetCount;
+  }
+  public void setWidgetCount(Integer widgetCount) {
+    this.widgetCount = widgetCount;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
+    DashboardDTO dashboardDTO = (DashboardDTO) o;
+    return Objects.equals(this.id, dashboardDTO.id) && Objects.equals(this.title, dashboardDTO.title) && Objects.equals(this.widgetCount, dashboardDTO.widgetCount);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(id, title, widgetCount);
+  }
+
+  @Override
+  public String toString() {
+    StringBuilder sb = new StringBuilder();
+    sb.append("DashboardDTO{");
+    sb.append(" id:").append(id).append(",");
+    sb.append(" title:").append(title).append(",");
+    sb.append(" widgetCount:").append(widgetCount);
+    sb.append("}");
+    return sb.toString();
+  }
+
+
+}

multiapi-engine/src/test/resources/openapigenerator/testExternalPathItemRefsGeneration/paths/dashboard.yml

@@ -0,0 +1,18 @@
+---
+# A standalone Path Item Object, referenced from the root contract via
+# `paths: /dashboard: { $ref: './paths/dashboard.yml' }`.
+# Note: the only top-level keys here are HTTP verbs (`get`) - there is NO
+# `$ref` verb, which is why `OpenApiUtil.mapApiGroups` filtering for REST
+# verbs finds nothing when it sees the *reference* node in the root file.
+get:
+  summary: Get the dashboard
+  operationId: getDashboard
+  tags:
+    - dashboard
+  responses:
+    '200':
+      description: The requested dashboard
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Dashboard"