feat/recursive reference

src/Microsoft.OpenApi/Interfaces/IOpenApiReferenceHolder.cs

@@ -15,7 +15,11 @@ public interface IOpenApiReferenceHolder<out T, V> : IOpenApiReferenceHolder whe
         /// <summary>
         /// Gets the resolved target object.
         /// </summary>
-        T Target { get; }
+        V Target { get; }
+        /// <summary>
+        /// Gets the recursively resolved target object.
+        /// </summary>
+        T RecursiveTarget { get; }
         /// <summary>
         /// Copy the reference as a target element with overrides.
         /// </summary>

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiCallback.cs

@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the callback object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiCallback : IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiCallback>
+public interface IOpenApiCallback : IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiCallback>, IOpenApiReferenceable
 {
     /// <summary>
     /// A Path Item Object used to define a callback request and expected responses.

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiExample.cs

@@ -7,7 +7,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the example object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiExample : IOpenApiDescribedElement, IOpenApiSummarizedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiExample>
+public interface IOpenApiExample : IOpenApiDescribedElement, IOpenApiSummarizedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiExample>, IOpenApiReferenceable
 {
     /// <summary>
     /// Embedded literal example. The value field and externalValue field are mutually

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiHeader.cs

@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the headers object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiHeader : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiHeader>
+public interface IOpenApiHeader : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiHeader>, IOpenApiReferenceable
 {
     /// <summary>
     /// Determines whether this header is mandatory.

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiLink.cs

@@ -7,7 +7,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the link object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiLink : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiLink>
+public interface IOpenApiLink : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiLink>, IOpenApiReferenceable
 {
     /// <summary>
     /// A relative or absolute reference to an OAS operation.

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiParameter.cs

@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the parameter object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiParameter>
+public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiParameter>, IOpenApiReferenceable
 {
     /// <summary>
     /// REQUIRED. The name of the parameter. Parameter names are case sensitive.

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiPathItem.cs

@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the path item object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiPathItem : IOpenApiDescribedElement, IOpenApiSummarizedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiPathItem>
+public interface IOpenApiPathItem : IOpenApiDescribedElement, IOpenApiSummarizedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiPathItem>, IOpenApiReferenceable
 {
     /// <summary>
     /// Gets the definition of operations on this path.

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiRequestBody.cs

@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the request body object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiRequestBody : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiRequestBody>
+public interface IOpenApiRequestBody : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiRequestBody>, IOpenApiReferenceable
 {
     /// <summary>
     /// Determines if the request body is required in the request. Defaults to false.

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiResponse.cs

@@ -7,7 +7,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the response object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiResponse : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiResponse>
+public interface IOpenApiResponse : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiResponse>, IOpenApiReferenceable
 {
     /// <summary>
     /// Maps a header name to its definition.

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSchema.cs

@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the schema object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiSchema>
+public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiSchema>, IOpenApiReferenceable
 {
 
     /// <summary>

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSecurityScheme.cs

@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the security scheme object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiSecurityScheme : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiSecurityScheme>
+public interface IOpenApiSecurityScheme : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiSecurityScheme>, IOpenApiReferenceable
 {
     /// <summary>
     /// REQUIRED. The type of the security scheme. Valid values are "apiKey", "http", "oauth2", "openIdConnect".

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiTag.cs

@@ -6,7 +6,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the path item object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiTag : IOpenApiSerializable, IOpenApiReadOnlyExtensible, IOpenApiReadOnlyDescribedElement, IShallowCopyable<IOpenApiTag>
+public interface IOpenApiTag : IOpenApiReadOnlyExtensible, IOpenApiReadOnlyDescribedElement, IShallowCopyable<IOpenApiTag>, IOpenApiReferenceable
 {
     /// <summary>
     /// The name of the tag.

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -463,16 +463,14 @@ public void SetReferenceHostDocument()
         /// <summary>
         /// Load the referenced <see cref="IOpenApiReferenceable"/> object from a <see cref="OpenApiReference"/> object
         /// </summary>
-        internal T? ResolveReferenceTo<T>(OpenApiReference reference) where T : class, IOpenApiReferenceable
+        internal T? ResolveReferenceTo<T>(OpenApiReference reference) where T : IOpenApiReferenceable
         {
-            if (reference.IsExternal)
-            {
-                return ResolveReference(reference, true) as T;
-            }
-            else
+
+            if (ResolveReference(reference, reference.IsExternal) is T result)
             {
-                return ResolveReference(reference, false) as T;
+                return result;
             }
+            return default;
         }
 
         /// <summary>

src/Microsoft.OpenApi/Models/OpenApiHeader.cs

@@ -17,7 +17,7 @@ namespace Microsoft.OpenApi.Models
     /// Header Object.
     /// The Header Object follows the structure of the Parameter Object.
     /// </summary>
-    public class OpenApiHeader : IOpenApiHeader, IOpenApiReferenceable, IOpenApiExtensible
+    public class OpenApiHeader : IOpenApiHeader, IOpenApiExtensible
     {
         /// <inheritdoc/>
         public string Description { get; set; }
@@ -174,7 +174,7 @@ public void SerializeAsV2(IOpenApiWriter writer)
 
             // schema
             var targetSchema = Schema switch {
-                OpenApiSchemaReference schemaReference => schemaReference.Target,
+                OpenApiSchemaReference schemaReference => schemaReference.RecursiveTarget,
                 OpenApiSchema schema => schema,
                 _ => null,
             };

src/Microsoft.OpenApi/Models/OpenApiParameter.cs

@@ -17,7 +17,7 @@
     /// <summary>
     /// Parameter Object.
     /// </summary>
-    public class OpenApiParameter : IOpenApiReferenceable, IOpenApiExtensible, IOpenApiParameter
+    public class OpenApiParameter : IOpenApiExtensible, IOpenApiParameter
     {
         private bool? _explode;
         private ParameterStyle? _style;
@@ -174,11 +174,11 @@
             writer.WriteStartObject();
 
             // in
             if (this is OpenApiFormDataParameter)
             {
                 writer.WriteProperty(OpenApiConstants.In, "formData");
             }
             else if (this is OpenApiBodyParameter)
             {
                 writer.WriteProperty(OpenApiConstants.In, "body");
             }
@@ -202,7 +202,7 @@
             var extensionsClone = new Dictionary<string, IOpenApiExtension>(Extensions);
 
             // schema
             if (this is OpenApiBodyParameter)
             {
                 writer.WriteOptionalObject(OpenApiConstants.Schema, Schema, (w, s) => s.SerializeAsV2(w));
             }
@@ -232,7 +232,7 @@
                 // enum
                 // multipleOf
                 var targetSchema = Schema switch {
-                    OpenApiSchemaReference schemaReference => schemaReference.Target,
+                    OpenApiSchemaReference schemaReference => schemaReference.RecursiveTarget,
                     OpenApiSchema schema => schema,
                     _ => null,
                 };
@@ -313,14 +313,14 @@
     /// <summary>
     /// Body parameter class to propagate information needed for <see cref="OpenApiParameter.SerializeAsV2"/>
     /// </summary>
     internal class OpenApiBodyParameter : OpenApiParameter
     {
     }
 
     /// <summary>
     /// Form parameter class to propagate information needed for <see cref="OpenApiParameter.SerializeAsV2"/>
     /// </summary>
     internal class OpenApiFormDataParameter : OpenApiParameter
     {
     }
 }

src/Microsoft.OpenApi/Models/OpenApiReference.cs

@@ -2,9 +2,11 @@
 // Licensed under the MIT license.
 
 using System;
+using System.Text.Json.Nodes;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models.Interfaces;
+using Microsoft.OpenApi.Reader.ParseNodes;
 using Microsoft.OpenApi.Writers;
 
 namespace Microsoft.OpenApi.Models
@@ -69,7 +71,7 @@
         /// <summary>
         /// The OpenApiDocument that is hosting the OpenApiReference instance. This is used to enable dereferencing the reference.
         /// </summary>
         public OpenApiDocument HostDocument { get => hostDocument; init => hostDocument = value; }
 
         /// <summary>
         /// Gets the full reference string for v3.0.
@@ -85,7 +87,7 @@
 
                 if (!Type.HasValue)
                 {
                     throw new ArgumentNullException(nameof(Type));
                 }
 
                 if (Type == ReferenceType.Tag)
@@ -121,7 +123,7 @@
 
                 if (!Type.HasValue)
                 {
                     throw new ArgumentNullException(nameof(Type));
                 }
 
                 if (Type == ReferenceType.Tag)
@@ -292,5 +294,25 @@
             Utils.CheckArgumentNull(currentDocument);
             hostDocument ??= currentDocument;
         }
+        #nullable enable
+        private static string? GetPropertyValueFromNode(JsonObject jsonObject, string key) =>
+        jsonObject.TryGetPropertyValue(key, out var valueNode) && valueNode is JsonValue valueCast && valueCast.TryGetValue<string>(out var strValue) ? strValue : null;
+        #nullable restore
+        internal void SetSummaryAndDescriptionFromMapNode(MapNode mapNode)
+        {
+            var (description, summary) = mapNode.JsonNode switch {
+                JsonObject jsonObject => (GetPropertyValueFromNode(jsonObject, OpenApiConstants.Description),
+                                            GetPropertyValueFromNode(jsonObject, OpenApiConstants.Summary)),
+                _ => (null, null)
+            };
+            if (!string.IsNullOrEmpty(description))
+            {
+                Description = description;
+            }
+            if (!string.IsNullOrEmpty(summary))
+            {
+                Summary = summary;
+            }
+        }
     }
 }

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -18,7 +18,7 @@
     /// <summary>
     /// The Schema Object allows the definition of input and output data types.
     /// </summary>
-    public class OpenApiSchema : IOpenApiReferenceable, IOpenApiExtensible, IOpenApiSchema
+    public class OpenApiSchema : IOpenApiExtensible, IOpenApiSchema
     {
         /// <inheritdoc />
         public string Title { get; set; }
@@ -265,7 +265,7 @@
         /// Initializes a copy of <see cref="IOpenApiSchema"/> object
         /// </summary>
         /// <param name="schema">The schema object to copy from.</param>
         internal OpenApiSchema(IOpenApiSchema schema)
         {
             Utils.CheckArgumentNull(schema);
             Title = schema.Title ?? Title;
@@ -337,7 +337,7 @@
             SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (writer, element) => element.SerializeAsV3(writer));
         }
 
         private static void SerializeBounds(IOpenApiWriter writer, OpenApiSpecVersion version, string propertyName, string exclusivePropertyName, string isExclusivePropertyName, decimal? value, decimal? exclusiveValue, bool? isExclusiveValue)
         {
             if (version >= OpenApiSpecVersion.OpenApi3_1)
             {

src/Microsoft.OpenApi/Models/References/BaseOpenApiReferenceHolder.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Writers;
 
@@ -8,14 +8,27 @@ namespace Microsoft.OpenApi.Models.References;
 /// </summary>
 /// <typeparam name="T">The concrete class implementation type for the model.</typeparam>
 /// <typeparam name="V">The interface type for the model.</typeparam>
-public abstract class BaseOpenApiReferenceHolder<T, V> : IOpenApiReferenceHolder<T, V> where T : class, IOpenApiReferenceable, V where V : IOpenApiSerializable
+public abstract class BaseOpenApiReferenceHolder<T, V> : IOpenApiReferenceHolder<T, V> where T : class, IOpenApiReferenceable, V where V : IOpenApiReferenceable, IOpenApiSerializable
 {
     /// <inheritdoc/>
-    public virtual T Target
+    public virtual V Target
     {
         get
         {
-            return Reference.HostDocument?.ResolveReferenceTo<T>(Reference);
+            if (Reference.HostDocument is null) return default;
+            return Reference.HostDocument.ResolveReferenceTo<V>(Reference);
+        }
+    }
+    /// <inheritdoc/>
+    public T RecursiveTarget
+    {
+        get
+        {
+            return Target switch {
+                BaseOpenApiReferenceHolder<T, V> recursiveTarget => recursiveTarget.RecursiveTarget,
+                T concrete => concrete,
+                _ => null
+            };
         }
     }
     /// <summary>

src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs

@@ -156,7 +156,7 @@ public string Description
         /// <inheritdoc/>
         public override void SerializeAsV31(IOpenApiWriter writer)
         {
-            SerializeAsWithoutLoops(writer, (w, element) => (element is IOpenApiSchema s ? CopyReferenceAsTargetElementWithOverrides(s) : element).SerializeAsV3(w));
+            SerializeAsWithoutLoops(writer, (w, element) => (element is IOpenApiSchema s ? CopyReferenceAsTargetElementWithOverrides(s) : element).SerializeAsV31(w));
         }
 
         /// <inheritdoc/>

src/Microsoft.OpenApi/Models/References/OpenApiTagReference.cs

@@ -17,7 +17,7 @@ public class OpenApiTagReference : BaseOpenApiReferenceHolder<OpenApiTag, IOpenA
         /// <summary>
         /// Resolved target of the reference.
         /// </summary>
-        public override OpenApiTag Target
+        public override IOpenApiTag Target
         {
             get
             {

src/Microsoft.OpenApi/Reader/V31/OpenApiSchemaDeserializer.cs

@@ -257,7 +257,9 @@ public static IOpenApiSchema LoadSchema(ParseNode node, OpenApiDocument hostDocu
             if (pointer != null)
             {
                 var reference = GetReferenceIdAndExternalResource(pointer);
-                return new OpenApiSchemaReference(reference.Item1, hostDocument, reference.Item2);
+                var result = new OpenApiSchemaReference(reference.Item1, hostDocument, reference.Item2);
+                result.Reference.SetSummaryAndDescriptionFromMapNode(mapNode);
+                return result;
             }
 
             var schema = new OpenApiSchema();

src/Microsoft.OpenApi/Services/CopyReferences.cs

@@ -14,7 +14,7 @@
     public OpenApiComponents Components = new();
 
     /// <inheritdoc/>
     public override void Visit(IOpenApiReferenceHolder referenceHolder)
     {
         switch (referenceHolder)
         {
@@ -85,7 +85,7 @@
         base.Visit(referenceHolder);
     }
 
-    private void AddSchemaToComponents(OpenApiSchema schema, string referenceId = null)
+    private void AddSchemaToComponents(IOpenApiSchema schema, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureSchemasExist();
@@ -95,7 +95,7 @@
         }
     }
 
-    private void AddParameterToComponents(OpenApiParameter parameter, string referenceId = null)
+    private void AddParameterToComponents(IOpenApiParameter parameter, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureParametersExist();
@@ -105,7 +105,7 @@
         }
     }
 
-    private void AddResponseToComponents(OpenApiResponse response, string referenceId = null)
+    private void AddResponseToComponents(IOpenApiResponse response, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureResponsesExist();
@@ -114,7 +114,7 @@
             Components.Responses.Add(referenceId, response);
         }
     }
-    private void AddRequestBodyToComponents(OpenApiRequestBody requestBody, string referenceId = null)
+    private void AddRequestBodyToComponents(IOpenApiRequestBody requestBody, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureRequestBodiesExist();
@@ -123,7 +123,7 @@
             Components.RequestBodies.Add(referenceId, requestBody);
         }
     }
-    private void AddLinkToComponents(OpenApiLink link, string referenceId = null)
+    private void AddLinkToComponents(IOpenApiLink link, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureLinksExist();
@@ -132,7 +132,7 @@
             Components.Links.Add(referenceId, link);
         }
     }
-    private void AddCallbackToComponents(OpenApiCallback callback, string referenceId = null)
+    private void AddCallbackToComponents(IOpenApiCallback callback, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureCallbacksExist();
@@ -141,7 +141,7 @@
             Components.Callbacks.Add(referenceId, callback);
         }
     }
-    private void AddHeaderToComponents(OpenApiHeader header, string referenceId = null)
+    private void AddHeaderToComponents(IOpenApiHeader header, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureHeadersExist();
@@ -150,7 +150,7 @@
             Components.Headers.Add(referenceId, header);
         }
     }
-    private void AddExampleToComponents(OpenApiExample example, string referenceId = null)
+    private void AddExampleToComponents(IOpenApiExample example, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureExamplesExist();
@@ -159,7 +159,7 @@
             Components.Examples.Add(referenceId, example);
         }
     }
-    private void AddPathItemToComponents(OpenApiPathItem pathItem, string referenceId = null)
+    private void AddPathItemToComponents(IOpenApiPathItem pathItem, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsurePathItemsExist();
@@ -168,7 +168,7 @@
             Components.PathItems.Add(referenceId, pathItem);
         }
     }
-    private void AddSecuritySchemeToComponents(OpenApiSecurityScheme securityScheme, string referenceId = null)
+    private void AddSecuritySchemeToComponents(IOpenApiSecurityScheme securityScheme, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureSecuritySchemesExist();