feat: enables references as components

Signed-off-by: Vincent Biret <[email protected]>

Author: baywet

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

@@ -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

@@ -232,7 +232,7 @@ public void SerializeAsV2(IOpenApiWriter writer)
                 // enum
                 // multipleOf
                 var targetSchema = Schema switch {
-                    OpenApiSchemaReference schemaReference => schemaReference.Target,
+                    OpenApiSchemaReference schemaReference => schemaReference.RecursiveTarget,
                     OpenApiSchema schema => schema,
                     _ => null,
                 };

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
@@ -292,5 +294,25 @@ internal void EnsureHostDocumentIsSet(OpenApiDocument currentDocument)
             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 @@ namespace Microsoft.OpenApi.Models
     /// <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; }

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/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

@@ -85,7 +85,7 @@ public override void Visit(IOpenApiReferenceHolder referenceHolder)
         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 AddSchemaToComponents(OpenApiSchema schema, string referenceId = nu
         }
     }
 
-    private void AddParameterToComponents(OpenApiParameter parameter, string referenceId = null)
+    private void AddParameterToComponents(IOpenApiParameter parameter, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureParametersExist();
@@ -105,7 +105,7 @@ private void AddParameterToComponents(OpenApiParameter parameter, string referen
         }
     }
 
-    private void AddResponseToComponents(OpenApiResponse response, string referenceId = null)
+    private void AddResponseToComponents(IOpenApiResponse response, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureResponsesExist();
@@ -114,7 +114,7 @@ private void AddResponseToComponents(OpenApiResponse response, string referenceI
             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 @@ private void AddRequestBodyToComponents(OpenApiRequestBody requestBody, string r
             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 @@ private void AddLinkToComponents(OpenApiLink link, string referenceId = null)
             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 @@ private void AddCallbackToComponents(OpenApiCallback callback, string referenceI
             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 @@ private void AddHeaderToComponents(OpenApiHeader header, string referenceId = nu
             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 @@ private void AddExampleToComponents(OpenApiExample example, string referenceId =
             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 @@ private void AddPathItemToComponents(OpenApiPathItem pathItem, string referenceI
             Components.PathItems.Add(referenceId, pathItem);
         }
     }
-    private void AddSecuritySchemeToComponents(OpenApiSecurityScheme securityScheme, string referenceId = null)
+    private void AddSecuritySchemeToComponents(IOpenApiSecurityScheme securityScheme, string referenceId = null)
     {
         EnsureComponentsExist();
         EnsureSecuritySchemesExist();