Fix schema generation for $ref with sibling description (OpenAPI 3.1)

multiapi-engine/pom.xml

@@ -4,7 +4,7 @@
 
   <groupId>com.sngular</groupId>
   <artifactId>multiapi-engine</artifactId>
-  <version>6.4.1</version>
+  <version>6.4.2</version>
   <packaging>jar</packaging>
 
   <properties>

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/common/tools/ApiTool.java

@@ -262,7 +262,10 @@ public static boolean hasName(JsonNode message) {
   }
 
   public static boolean hasRef(final JsonNode schema) {
-    return (hasNode(schema, "$ref") || schema.fieldNames().hasNext()) && schema.fieldNames().next().equals("$ref");
+    // OpenAPI 3.1 / JSON Schema 2020-12 allow sibling keywords next to `$ref`
+    // (e.g. `description`), and their ordering is not significant. A node is a
+    // reference whenever it declares a top-level `$ref`, regardless of position.
+    return hasNode(schema, "$ref");
   }
 
   public static boolean hasProperties(final JsonNode schema) {

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

@@ -175,6 +175,13 @@ public final class OpenApiGeneratorFixtures {
 					.clientPackage("com.sngular.multifileplugin.openapi31types.client")
 					.modelNameSuffix("DTO").build());
 
+	static final List<SpecFile> TEST_REF_WITH_DESCRIPTION = List
+			.of(SpecFile.builder().filePath("openapigenerator/testRefWithDescription/api-test.yml")
+					.apiPackage("com.sngular.multifileplugin.refwithdescription")
+					.modelPackage("com.sngular.multifileplugin.refwithdescription.model")
+					.clientPackage("com.sngular.multifileplugin.refwithdescription.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")
@@ -884,6 +891,25 @@ static Function<Path, Boolean> validateOpenApi31Types() {
     DEFAULT_MODEL_API, Collections.emptyList(), null);
   }
 
+	static Function<Path, Boolean> validateRefWithDescription() {
+
+		final String DEFAULT_TARGET_API = "generated/com/sngular/multifileplugin/refwithdescription";
+
+		final String DEFAULT_MODEL_API = "generated/com/sngular/multifileplugin/refwithdescription/model";
+
+		final String COMMON_PATH = "openapigenerator/testRefWithDescription/";
+
+		final String ASSETS_PATH = COMMON_PATH + "assets/";
+
+		final List<String> expectedTestApiFile = List.of(ASSETS_PATH + "OrderApi.java");
+
+		final List<String> expectedTestApiModelFiles = List.of(ASSETS_PATH + "AddressDTO.java",
+				ASSETS_PATH + "CustomerDTO.java", ASSETS_PATH + "OrderDTO.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";

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("testRefWithDescription", OpenApiGeneratorFixtures.TEST_REF_WITH_DESCRIPTION,
+            OpenApiGeneratorFixtures.validateRefWithDescription()),
         Arguments.of("testWebhooks", OpenApiGeneratorFixtures.TEST_WEBHOOKS,
             OpenApiGeneratorFixtures.validateWebhooks()),
         Arguments.of("testOpenApi31Union", OpenApiGeneratorFixtures.TEST_OPEN_API_31_UNION,

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

@@ -0,0 +1,55 @@
+---
+# Regression for OpenAPI 3.1 support: a `$ref` may carry sibling keywords such as
+# `description`. The generator must still resolve the reference regardless of the
+# relative ordering of `$ref` and its siblings (see issue: $ref + description).
+openapi: "3.1.0"
+info:
+  version: 1.0.0
+  title: Order API (OpenAPI 3.1)
+  license:
+    name: MIT
+servers:
+  - url: http://localhost:8080/v1
+tags:
+  - name: order
+paths:
+  /order:
+    get:
+      summary: Get an order
+      operationId: getOrder
+      tags:
+        - order
+      responses:
+        '200':
+          description: The requested order
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Order"
+components:
+  schemas:
+    Order:
+      type: object
+      properties:
+        id:
+          type: string
+        customer:
+          description: The customer that placed the order
+          $ref: "#/components/schemas/Customer"
+        shippingAddress:
+          $ref: "#/components/schemas/Address"
+          description: Where the order is shipped
+    Customer:
+      type: object
+      properties:
+        name:
+          type: string
+        email:
+          type: string
+    Address:
+      type: object
+      properties:
+        street:
+          type: string
+        city:
+          type: string

multiapi-engine/src/test/resources/openapigenerator/testRefWithDescription/assets/AddressDTO.java

@@ -0,0 +1,94 @@
+package com.sngular.multifileplugin.refwithdescription.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 = AddressDTO.AddressDTOBuilder.class)
+public class AddressDTO {
+
+  @JsonProperty(value ="city")
+  private String city;
+  @JsonProperty(value ="street")
+  private String street;
+
+  private AddressDTO(AddressDTOBuilder builder) {
+    this.city = builder.city;
+    this.street = builder.street;
+
+  }
+
+  public static AddressDTO.AddressDTOBuilder builder() {
+    return new AddressDTO.AddressDTOBuilder();
+  }
+
+  @JsonPOJOBuilder(buildMethodName = "build", withPrefix = "")
+  public static class AddressDTOBuilder {
+
+    private String city;
+    private String street;
+
+    public AddressDTO.AddressDTOBuilder city(String city) {
+      this.city = city;
+      return this;
+    }
+
+    public AddressDTO.AddressDTOBuilder street(String street) {
+      this.street = street;
+      return this;
+    }
+
+    public AddressDTO build() {
+      AddressDTO addressDTO = new AddressDTO(this);
+      return addressDTO;
+    }
+  }
+
+  @Schema(name = "city", required = false)
+  public String getCity() {
+    return city;
+  }
+  public void setCity(String city) {
+    this.city = city;
+  }
+
+  @Schema(name = "street", required = false)
+  public String getStreet() {
+    return street;
+  }
+  public void setStreet(String street) {
+    this.street = street;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
+    AddressDTO addressDTO = (AddressDTO) o;
+    return Objects.equals(this.city, addressDTO.city) && Objects.equals(this.street, addressDTO.street);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(city, street);
+  }
+
+  @Override
+  public String toString() {
+    StringBuilder sb = new StringBuilder();
+    sb.append("AddressDTO{");
+    sb.append(" city:").append(city).append(",");
+    sb.append(" street:").append(street);
+    sb.append("}");
+    return sb.toString();
+  }
+
+
+}

multiapi-engine/src/test/resources/openapigenerator/testRefWithDescription/assets/CustomerDTO.java

@@ -0,0 +1,94 @@
+package com.sngular.multifileplugin.refwithdescription.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 = CustomerDTO.CustomerDTOBuilder.class)
+public class CustomerDTO {
+
+  @JsonProperty(value ="name")
+  private String name;
+  @JsonProperty(value ="email")
+  private String email;
+
+  private CustomerDTO(CustomerDTOBuilder builder) {
+    this.name = builder.name;
+    this.email = builder.email;
+
+  }
+
+  public static CustomerDTO.CustomerDTOBuilder builder() {
+    return new CustomerDTO.CustomerDTOBuilder();
+  }
+
+  @JsonPOJOBuilder(buildMethodName = "build", withPrefix = "")
+  public static class CustomerDTOBuilder {
+
+    private String name;
+    private String email;
+
+    public CustomerDTO.CustomerDTOBuilder name(String name) {
+      this.name = name;
+      return this;
+    }
+
+    public CustomerDTO.CustomerDTOBuilder email(String email) {
+      this.email = email;
+      return this;
+    }
+
+    public CustomerDTO build() {
+      CustomerDTO customerDTO = new CustomerDTO(this);
+      return customerDTO;
+    }
+  }
+
+  @Schema(name = "name", required = false)
+  public String getName() {
+    return name;
+  }
+  public void setName(String name) {
+    this.name = name;
+  }
+
+  @Schema(name = "email", required = false)
+  public String getEmail() {
+    return email;
+  }
+  public void setEmail(String email) {
+    this.email = email;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
+    CustomerDTO customerDTO = (CustomerDTO) o;
+    return Objects.equals(this.name, customerDTO.name) && Objects.equals(this.email, customerDTO.email);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(name, email);
+  }
+
+  @Override
+  public String toString() {
+    StringBuilder sb = new StringBuilder();
+    sb.append("CustomerDTO{");
+    sb.append(" name:").append(name).append(",");
+    sb.append(" email:").append(email);
+    sb.append("}");
+    return sb.toString();
+  }
+
+
+}

multiapi-engine/src/test/resources/openapigenerator/testRefWithDescription/assets/OrderApi.java

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