OpenAPI: Fix $ref handling for array circular references

src/OpenApi/src/Extensions/JsonNodeSchemaExtensions.cs

@@ -175,13 +175,16 @@ internal static void ApplyDefaultValue(this JsonNode schema, object? defaultValu
             return;
         }
 
+        var isReferencedSchema = schema[OpenApiConstants.SchemaId] is null;
+        var schemaAttribute = isReferencedSchema ? OpenApiConstants.RefDefaultAnnotation : OpenApiSchemaKeywords.DefaultKeyword;
+
         if (defaultValue is null)
         {
-            schema[OpenApiSchemaKeywords.DefaultKeyword] = null;
+            schema[schemaAttribute] = null;
         }
         else
         {
-            schema[OpenApiSchemaKeywords.DefaultKeyword] = JsonSerializer.SerializeToNode(defaultValue, jsonTypeInfo);
+            schema[schemaAttribute] = JsonSerializer.SerializeToNode(defaultValue, jsonTypeInfo);
         }
     }
 

src/OpenApi/src/Extensions/OpenApiDocumentExtensions.cs

@@ -17,25 +17,27 @@ internal static class OpenApiDocumentExtensions
     /// <returns>An <see cref="IOpenApiSchema"/> with a reference to the stored schema.</returns>
     public static IOpenApiSchema AddOpenApiSchemaByReference(this OpenApiDocument document, string schemaId, IOpenApiSchema schema)
     {
-        document.Components ??= new();
-        document.Components.Schemas ??= new Dictionary<string, IOpenApiSchema>();
-        document.Components.Schemas[schemaId] = schema;
+        // Make sure the document has a workspace,
+        // AddComponent will add it to the workspace when adding the component.
         document.Workspace ??= new();
-        var location = document.BaseUri + "/components/schemas/" + schemaId;
-        document.Workspace.RegisterComponentForDocument(document, schema, location);
+        // AddComponent will only add the schema if it doesn't already exist.
+        document.AddComponent(schemaId, schema);
 
         object? description = null;
         object? example = null;
+        object? defaultAnnotation = null;
         if (schema is OpenApiSchema actualSchema)
         {
             actualSchema.Metadata?.TryGetValue(OpenApiConstants.RefDescriptionAnnotation, out description);
             actualSchema.Metadata?.TryGetValue(OpenApiConstants.RefExampleAnnotation, out example);
+            actualSchema.Metadata?.TryGetValue(OpenApiConstants.RefDefaultAnnotation, out defaultAnnotation);
         }
 
         return new OpenApiSchemaReference(schemaId, document)
         {
             Description = description as string,
             Examples = example is JsonNode exampleJson ? [exampleJson] : null,
+            Default = defaultAnnotation as JsonNode,
         };
     }
 }

src/OpenApi/src/Schemas/OpenApiJsonSchema.Helpers.cs

@@ -355,7 +355,11 @@ public static void ReadProperty(ref Utf8JsonReader reader, string propertyName,
                 schema.Metadata ??= new Dictionary<string, object>();
                 schema.Metadata[OpenApiConstants.RefDescriptionAnnotation] = reader.GetString() ?? string.Empty;
                 break;
-
+            case OpenApiConstants.RefDefaultAnnotation:
+                reader.Read();
+                schema.Metadata ??= new Dictionary<string, object>();
+                schema.Metadata[OpenApiConstants.RefDefaultAnnotation] = ReadJsonNode(ref reader)!;
+                break;
             default:
                 reader.Skip();
                 break;

src/OpenApi/src/Services/OpenApiConstants.cs

@@ -13,6 +13,7 @@ internal static class OpenApiConstants
     internal const string DescriptionId = "x-aspnetcore-id";
     internal const string SchemaId = "x-schema-id";
     internal const string RefId = "x-ref-id";
+    internal const string RefDefaultAnnotation = "x-ref-default";
     internal const string RefDescriptionAnnotation = "x-ref-description";
     internal const string RefExampleAnnotation = "x-ref-example";
     internal const string RefKeyword = "$ref";

src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs

@@ -265,6 +265,20 @@ internal static IOpenApiSchema ResolveReferenceForSchema(OpenApiDocument documen
     {
         var schema = UnwrapOpenApiSchema(inputSchema);
 
+        if (inputSchema is OpenApiSchema && schema.Metadata is not null &&
+            !schema.Metadata.ContainsKey(OpenApiConstants.RefId) &&
+            schema.Metadata.TryGetValue(OpenApiConstants.SchemaId, out var referenceId) &&
+            referenceId is string referenceIdString)
+        {
+            var targetReferenceId = baseSchemaId is not null
+                ? $"{baseSchemaId}{referenceIdString}"
+                : referenceIdString;
+            if (!string.IsNullOrEmpty(targetReferenceId))
+            {
+                document.AddOpenApiSchemaByReference(targetReferenceId, schema);
+            }
+        }
+
         if (schema.Metadata is not null &&
             schema.Metadata.TryGetValue(OpenApiConstants.SchemaId, out var resolvedBaseSchemaId))
         {
@@ -347,14 +361,14 @@ internal static IOpenApiSchema ResolveReferenceForSchema(OpenApiDocument documen
         // we don't want to replace the top-level inline schema with a reference to itself. We want to replace
         // inline schemas to reference schemas for all schemas referenced in the top-level schema though (such as
         // `allOf`, `oneOf`, `anyOf`, `items`, `properties`, etc.) which is why `isTopLevel` is only set once.
-        if (schema is OpenApiSchema && schema.Metadata is not null &&
+        if (inputSchema is OpenApiSchema && schema.Metadata is not null &&
             !schema.Metadata.ContainsKey(OpenApiConstants.RefId) &&
-            schema.Metadata.TryGetValue(OpenApiConstants.SchemaId, out var referenceId) &&
-            referenceId is string referenceIdString)
+            schema.Metadata.TryGetValue(OpenApiConstants.SchemaId, out var referenceId2) &&
+            referenceId2 is string referenceIdString2)
         {
             var targetReferenceId = baseSchemaId is not null
-                ? $"{baseSchemaId}{referenceIdString}"
-                : referenceIdString;
+                ? $"{baseSchemaId}{referenceIdString2}"
+                : referenceIdString2;
             if (!string.IsNullOrEmpty(targetReferenceId))
             {
                 return document.AddOpenApiSchemaByReference(targetReferenceId, schema);

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Services/OpenApiSchemaService/OpenApiSchemaService.RequestBodySchemas.cs

@@ -984,8 +984,9 @@ private void VerifyOptionalEnum(OpenApiDocument document)
         var property = properties["status"];
 
         Assert.NotNull(property);
-        Assert.Equal(3, property.Enum.Count);
-        Assert.Equal("Approved", property.Default.GetValue<string>());
+        var statusReference = Assert.IsType<OpenApiSchemaReference>(property);
+        Assert.Equal(3, statusReference.RecursiveTarget.Enum.Count);
+        Assert.Equal("Approved", statusReference.Default.GetValue<string>());
     }
 
     [ApiController]

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Transformers/Implementations/OpenApiSchemaReferenceTransformerTests.cs

@@ -1122,6 +1122,38 @@
         });
     }
 
+    // Test for: https://github.com/dotnet/aspnetcore/issues/64048
+    public static object[][] CircularReferencesWithArraysHandlers =>
+    [
+        [(CircularReferenceWithArrayRootOrderArrayFirst dto) => { }],
+        [(CircularReferenceWithArrayRootOrderArrayLast dto) => { }],
+    ];
+
+    [Theory]
+    [MemberData(nameof(CircularReferencesWithArraysHandlers))]
+    public async Task HandlesCircularReferencesWithArraysRegardlessOfPropertyOrder(Delegate requestHandler)
+    {
+        var builder = CreateBuilder();
+        builder.MapPost("/", requestHandler);
+
+        await VerifyOpenApiDocument(builder, (OpenApiDocument document) =>
+        {
+            Assert.NotNull(document.Components?.Schemas);
+            var schema = document.Components.Schemas["CircularReferenceWithArrayModel"];
+            Assert.Equal(JsonSchemaType.Object, schema.Type);
+            Assert.NotNull(schema.Properties);
+            Assert.Collection(schema.Properties,
+                property =>
+                {
+                    Assert.Equal("selfArray", property.Key);
+                    var arraySchema = Assert.IsType<OpenApiSchema>(property.Value);
+                    Assert.Equal(JsonSchemaType.Array, arraySchema.Type);
+                    var itemReference = Assert.IsType<OpenApiSchemaReference>(arraySchema.Items);
+                    Assert.Equal("#/components/schemas/CircularReferenceWithArrayModel", itemReference.Reference.ReferenceV3);
+                });
+        });
+    }
+
     // Test models for issue 61194
     private class Config
     {
@@ -1203,5 +1235,23 @@
     {
         public int Id { get; set; }
     }
+
+    // Test models for issue 64048
+    public class CircularReferenceWithArrayRootOrderArrayLast
+    {
+        public CircularReferenceWithArrayModel Item { get; set; }
+        public ICollection<CircularReferenceWithArrayModel> ItemArray { get; set; }
+    }
+
+    public class CircularReferenceWithArrayRootOrderArrayFirst
+    {
+        public ICollection<CircularReferenceWithArrayModel> ItemArray { get; set; }
+        public CircularReferenceWithArrayModel Item { get; set; }
+    }
+
+    public class CircularReferenceWithArrayModel
+    {
+        public ICollection<CircularReferenceWithArrayModel> SelfArray { get; set; }
+    }
 }
 #nullable restore