fix: use array item schema ref when available instead of inline schema

Signed-off-by: Michael Edgar <[email protected]>

Author: MikeEdgar

core/src/main/java/io/smallrye/openapi/runtime/io/schema/SchemaFactory.java

@@ -340,7 +340,7 @@ public static Schema includeTypeSchema(AnnotationScannerContext context, Schema
         if (schema.getType() != null && schema.getType().contains(Schema.SchemaType.ARRAY) && implSchema != null) {
             // If the @Schema annotation indicates an array type, then use the Schema
             // generated from the implementation Class as the "items" for the array.
-            schema.setItems(implSchema);
+            schema.setItems(lookupRef(context, type, implSchema));
         } else if (implSchema != null) {
             // If there is an impl class - merge the @Schema properties *onto* the schema
             // generated from the Class so that the annotation properties override the class
@@ -727,7 +727,21 @@ public static Schema schemaRegistration(final AnnotationScannerContext context,
 
         if (allowRegistration(context, schemaRegistry, type, schema)) {
             schema = schemaRegistry.register(type, context.getJsonViews(), schema);
-        } else if (schemaRegistry != null && schemaRegistry.hasRef(type, context.getJsonViews())) {
+        } else {
+            schema = lookupRef(context, type, schema);
+        }
+
+        return schema;
+    }
+
+    /**
+     * If the given type is found in the registry and has a reference, replace the
+     * given schema with a schema reference. Otherwise, simply return the schema unaltered.
+     */
+    static Schema lookupRef(AnnotationScannerContext context, Type type, Schema schema) {
+        SchemaRegistry schemaRegistry = context.getSchemaRegistry();
+
+        if (schemaRegistry != null && schemaRegistry.hasRef(type, context.getJsonViews())) {
             schema = schemaRegistry.lookupRef(type, context.getJsonViews());
         }
 

core/src/test/java/io/smallrye/openapi/runtime/scanner/StandaloneSchemaScanTest.java

@@ -968,4 +968,25 @@ class ChildClass extends ParentClass implements FieldInterface {
     void testParentClassFieldSchemaAnnotation() throws IOException, JSONException {
         assertJsonEquals("components.schemas.annotated-parent-field.json", ParentClassFieldSchemaAnnotationTestClasses.CLASSES);
     }
+
+    @Test
+    void testArrayItemsUseAvailableReference() throws IOException, JSONException {
+        class ImmutableList<T> extends java.util.ArrayList<T> {
+            private static final long serialVersionUID = 1L;
+        }
+
+        @Schema(name = "Greeting", description = "A greeting message")
+        class Greeting {
+            @Schema(description = "The message to be displayed")
+            String message;
+        }
+
+        @Schema(name = "Response")
+        class Response {
+            @Schema(type = SchemaType.ARRAY, implementation = Greeting.class, description = "An array of greetings")
+            ImmutableList<Greeting> greetings;
+        }
+
+        assertJsonEquals("components.schemas.array-items-reference.json", ImmutableList.class, Greeting.class, Response.class);
+    }
 }

core/src/test/resources/io/smallrye/openapi/runtime/scanner/components.schemas.array-items-reference.json

@@ -0,0 +1,29 @@
+{
+  "openapi" : "3.1.0",
+  "components" : {
+    "schemas" : {
+      "Greeting" : {
+        "description" : "A greeting message",
+        "type" : "object",
+        "properties" : {
+          "message" : {
+            "type" : "string",
+            "description" : "The message to be displayed"
+          }
+        }
+      },
+      "Response" : {
+        "type" : "object",
+        "properties" : {
+          "greetings" : {
+            "description" : "An array of greetings",
+            "type" : "array",
+            "items" : {
+              "$ref" : "#/components/schemas/Greeting"
+            }
+          }
+        }
+      }
+    }
+  }
+}