fix: makes reference serialization object generic

baywet · baywet · commit f0802e5cb197 · 2025-06-05T17:38:08.000-04:00
Signed-off-by: Vincent Biret &lt;vibiret@microsoft.com&gt;
diff --git a/src/Microsoft.OpenApi/Interfaces/IOpenApiReferenceHolder.cs b/src/Microsoft.OpenApi/Interfaces/IOpenApiReferenceHolder.cs
@@ -8,7 +8,8 @@ namespace Microsoft.OpenApi
     /// </summary>
     /// <typeparam name="T">The type of the target being referenced</typeparam>
     /// <typeparam name="V">The type of the interface implemented by both the target and the reference type</typeparam>
-    public interface IOpenApiReferenceHolder<out T, V> : IOpenApiReferenceHolder where T : IOpenApiReferenceable, V
+    /// <typeparam name="U">The type for the reference holding the additional fields and annotations</typeparam>
+    public interface IOpenApiReferenceHolder<out T, V, U> : IOpenApiReferenceHolder<U> where T : IOpenApiReferenceable, V where U : OpenApiReference
     {
         /// <summary>
         /// Gets the resolved target object.
@@ -28,7 +29,7 @@ public interface IOpenApiReferenceHolder<out T, V> : IOpenApiReferenceHolder whe
     /// <summary>
     /// A generic interface for OpenApiReferenceable objects that have a target.
     /// </summary>
-    public interface IOpenApiReferenceHolder : IOpenApiSerializable
+    public interface IOpenApiReferenceHolder<U> : IOpenApiSerializable where U : OpenApiReference
     {
         /// <summary>
         /// Indicates if object is populated with data or is just a reference to the data
@@ -38,6 +39,6 @@ public interface IOpenApiReferenceHolder : IOpenApiSerializable
         /// <summary>
         /// Reference object.
         /// </summary>
-        OpenApiReference Reference { get; init; }
+        U Reference { get; init; }
     }
 }
diff --git a/src/Microsoft.OpenApi/Models/JsonSchemaReference.cs b/src/Microsoft.OpenApi/Models/JsonSchemaReference.cs
@@ -12,7 +12,7 @@ namespace Microsoft.OpenApi
     /// Schema reference information that includes metadata annotations from JSON Schema 2020-12.
     /// This class extends OpenApiReference to provide schema-specific metadata override capabilities.
     /// </summary>
-    public class OpenApiSchemaReferenceInformation : OpenApiReference
+    public class JsonSchemaReference : OpenApiReference
     {
         /// <summary>
         /// A default value which by default SHOULD override that of the referenced component.
@@ -53,12 +53,12 @@ public class OpenApiSchemaReferenceInformation : OpenApiReference
         /// <summary>
         /// Parameterless constructor
         /// </summary>
-        public OpenApiSchemaReferenceInformation() { }
+        public JsonSchemaReference() { }
 
         /// <summary>
-        /// Initializes a copy instance of the <see cref="OpenApiSchemaReferenceInformation"/> object
+        /// Initializes a copy instance of the <see cref="JsonSchemaReference"/> object
         /// </summary>
-        public OpenApiSchemaReferenceInformation(OpenApiSchemaReferenceInformation reference) : base(reference)
+        public JsonSchemaReference(JsonSchemaReference reference) : base(reference)
         {
             Utils.CheckArgumentNull(reference);
             Default = reference.Default;
@@ -70,7 +70,7 @@ public OpenApiSchemaReferenceInformation(OpenApiSchemaReferenceInformation refer
         }
 
         /// <summary>
-        /// Serialize <see cref="OpenApiSchemaReferenceInformation"/> to Open Api v3.1.
+        /// Serialize <see cref="JsonSchemaReference"/> to Open Api v3.1.
         /// </summary>
         public override void SerializeAsV31(IOpenApiWriter writer)
         {
diff --git a/src/Microsoft.OpenApi/Models/References/BaseOpenApiReferenceHolder.cs b/src/Microsoft.OpenApi/Models/References/BaseOpenApiReferenceHolder.cs
@@ -6,7 +6,8 @@ namespace Microsoft.OpenApi;
 /// </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 : IOpenApiReferenceable, IOpenApiSerializable
+/// <typeparam name="U">The type for the reference holding the additional fields and annotations</typeparam>
+public abstract class BaseOpenApiReferenceHolder<T, V, U> : IOpenApiReferenceHolder<T, V, U> where T : class, IOpenApiReferenceable, V where V : IOpenApiReferenceable, IOpenApiSerializable where U : OpenApiReference, new()
 {
     /// <inheritdoc/>
     public virtual V? Target
@@ -23,7 +24,7 @@ public T? RecursiveTarget
         get
         {
             return Target switch {
-                BaseOpenApiReferenceHolder<T, V> recursiveTarget => recursiveTarget.RecursiveTarget,
+                BaseOpenApiReferenceHolder<T, V, U> recursiveTarget => recursiveTarget.RecursiveTarget,
                 T concrete => concrete,
                 _ => null
             };
@@ -34,7 +35,7 @@ public T? RecursiveTarget
     /// Copy constructor
     /// </summary>
     /// <param name="source">The parameter reference to copy</param>
-    protected BaseOpenApiReferenceHolder(BaseOpenApiReferenceHolder<T, V> source)
+    protected BaseOpenApiReferenceHolder(BaseOpenApiReferenceHolder<T, V, U> source)
     {
         Utils.CheckArgumentNull(source);
         Reference = new(source.Reference);
@@ -58,7 +59,7 @@ protected BaseOpenApiReferenceHolder(string referenceId, OpenApiDocument? hostDo
         // we're not checking for null hostDocument as it's optional and can be set via additional methods by a walker
         // this way object initialization of a whole document is supported
 
-        Reference = new OpenApiReference()
+        Reference = new U()
         {
             Id = referenceId,
             HostDocument = hostDocument,
@@ -71,10 +72,10 @@ protected BaseOpenApiReferenceHolder(string referenceId, OpenApiDocument? hostDo
 
 #if NETSTANDARD2_1_OR_GREATER
     /// <inheritdoc/>
-    public required OpenApiReference Reference { get; init; }
+    public required U Reference { get; init; }
 #else
     /// <inheritdoc/>
-    public OpenApiReference Reference { get; init; }
+    public U Reference { get; init; }
 #endif
     /// <inheritdoc/>
     public abstract V CopyReferenceAsTargetElementWithOverrides(V source);
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiCallbackReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiCallbackReference.cs
@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Callback Object Reference: A reference to a map of possible out-of band callbacks related to the parent operation.
     /// </summary>
-    public class OpenApiCallbackReference : BaseOpenApiReferenceHolder<OpenApiCallback, IOpenApiCallback>, IOpenApiCallback
+    public class OpenApiCallbackReference : BaseOpenApiReferenceHolder<OpenApiCallback, IOpenApiCallback, OpenApiReference>, IOpenApiCallback
     {
         /// <summary>
         /// Constructor initializing the reference object.
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiExampleReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiExampleReference.cs
@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Example Object Reference.
     /// </summary>
-    public class OpenApiExampleReference : BaseOpenApiReferenceHolder<OpenApiExample, IOpenApiExample>, IOpenApiExample
+    public class OpenApiExampleReference : BaseOpenApiReferenceHolder<OpenApiExample, IOpenApiExample, OpenApiReference>, IOpenApiExample
     {
         /// <summary>
         /// Constructor initializing the reference object.
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiHeaderReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiHeaderReference.cs
@@ -9,8 +9,8 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Header Object Reference.
     /// </summary>
-    public class OpenApiHeaderReference : BaseOpenApiReferenceHolder<OpenApiHeader, IOpenApiHeader>, IOpenApiHeader
-    {
+    public class OpenApiHeaderReference : BaseOpenApiReferenceHolder<OpenApiHeader, IOpenApiHeader, OpenApiReference>, IOpenApiHeader
+    { //TODO switch to the non summary version
         /// <summary>
         /// Constructor initializing the reference object.
         /// </summary>
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiLinkReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiLinkReference.cs
@@ -8,8 +8,8 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Link Object Reference.
     /// </summary>
-    public class OpenApiLinkReference : BaseOpenApiReferenceHolder<OpenApiLink, IOpenApiLink>, IOpenApiLink
-    {
+    public class OpenApiLinkReference : BaseOpenApiReferenceHolder<OpenApiLink, IOpenApiLink, OpenApiReference>, IOpenApiLink
+    {//TODO switch to the non summary version
         /// <summary>
         /// Constructor initializing the reference object.
         /// </summary>
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiParameterReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiParameterReference.cs
@@ -9,8 +9,8 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Parameter Object Reference.
     /// </summary>
-    public class OpenApiParameterReference : BaseOpenApiReferenceHolder<OpenApiParameter, IOpenApiParameter>, IOpenApiParameter
-    {
+    public class OpenApiParameterReference : BaseOpenApiReferenceHolder<OpenApiParameter, IOpenApiParameter, OpenApiReference>, IOpenApiParameter
+    {//TODO switch to the non summary version
         /// <summary>
         /// Constructor initializing the reference object.
         /// </summary>
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiPathItemReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiPathItemReference.cs
@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Path Item Object Reference: to describe the operations available on a single path.
     /// </summary>
-    public class OpenApiPathItemReference : BaseOpenApiReferenceHolder<OpenApiPathItem, IOpenApiPathItem>, IOpenApiPathItem
+    public class OpenApiPathItemReference : BaseOpenApiReferenceHolder<OpenApiPathItem, IOpenApiPathItem, OpenApiReference>, IOpenApiPathItem
     {
 
         /// <summary>
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiRequestBodyReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiRequestBodyReference.cs
@@ -9,8 +9,8 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Request Body Object Reference.
     /// </summary>
-    public class OpenApiRequestBodyReference : BaseOpenApiReferenceHolder<OpenApiRequestBody, IOpenApiRequestBody>, IOpenApiRequestBody
-    {
+    public class OpenApiRequestBodyReference : BaseOpenApiReferenceHolder<OpenApiRequestBody, IOpenApiRequestBody, OpenApiReference>, IOpenApiRequestBody
+    {//TODO switch to the non summary version
         /// <summary>
         /// Constructor initializing the reference object.
         /// </summary>
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiResponseReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiResponseReference.cs
@@ -8,8 +8,8 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Response Object Reference.
     /// </summary>
-    public class OpenApiResponseReference : BaseOpenApiReferenceHolder<OpenApiResponse, IOpenApiResponse>, IOpenApiResponse
-    {
+    public class OpenApiResponseReference : BaseOpenApiReferenceHolder<OpenApiResponse, IOpenApiResponse, OpenApiReference>, IOpenApiResponse
+    {//TODO switch to the non summary version
         /// <summary>
         /// Constructor initializing the reference object.
         /// </summary>
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs
@@ -10,14 +10,8 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Schema reference object
     /// </summary>
-    public class OpenApiSchemaReference : BaseOpenApiReferenceHolder<OpenApiSchema, IOpenApiSchema>, IOpenApiSchema
+    public class OpenApiSchemaReference : BaseOpenApiReferenceHolder<OpenApiSchema, IOpenApiSchema, JsonSchemaReference>, IOpenApiSchema
     {
-        private readonly OpenApiSchemaReferenceInformation _schemaReferenceInfo;
-
-        /// <summary>
-        /// The schema reference information containing metadata annotations
-        /// </summary>
-        public new OpenApiSchemaReferenceInformation Reference => _schemaReferenceInfo;
 
         /// <summary>
         /// Constructor initializing the reference object.
@@ -31,44 +25,27 @@ public class OpenApiSchemaReference : BaseOpenApiReferenceHolder<OpenApiSchema,
         /// </param>
         public OpenApiSchemaReference(string referenceId, OpenApiDocument? hostDocument = null, string? externalResource = null) : base(referenceId, hostDocument, ReferenceType.Schema, externalResource)
         {
-            _schemaReferenceInfo = new OpenApiSchemaReferenceInformation
-            {
-                Id = referenceId,
-                HostDocument = hostDocument,
-                Type = ReferenceType.Schema,
-                ExternalResource = externalResource
-            };
         }
         /// <summary>
         /// Copy constructor
         /// </summary>
         /// <param name="schema">The schema reference to copy</param>
         private OpenApiSchemaReference(OpenApiSchemaReference schema) : base(schema)
         {
-            _schemaReferenceInfo = new OpenApiSchemaReferenceInformation(schema._schemaReferenceInfo);
         }
 
         /// <inheritdoc/>
         public string? Description
         {
-            get => string.IsNullOrEmpty(_schemaReferenceInfo.Description) ? Target?.Description : _schemaReferenceInfo.Description;
-            set => _schemaReferenceInfo.Description = value;
-        }
-
-        /// <summary>
-        /// A short summary which by default SHOULD override that of the referenced component.
-        /// </summary>
-        public string? Summary
-        {
-            get => string.IsNullOrEmpty(_schemaReferenceInfo.Summary) ? null : _schemaReferenceInfo.Summary;
-            set => _schemaReferenceInfo.Summary = value;
+            get => string.IsNullOrEmpty(Reference.Description) ? Target?.Description : Reference.Description;
+            set => Reference.Description = value;
         }
 
         /// <inheritdoc/>
         public string? Title
         {
-            get => string.IsNullOrEmpty(_schemaReferenceInfo.Title) ? Target?.Title : _schemaReferenceInfo.Title;
-            set => _schemaReferenceInfo.Title = value;
+            get => string.IsNullOrEmpty(Reference.Title) ? Target?.Title : Reference.Title;
+            set => Reference.Title = value;
         }
         /// <inheritdoc/>
         public Uri? Schema { get => Target?.Schema; }
@@ -109,20 +86,20 @@ public string? Title
         /// <inheritdoc/>
         public JsonNode? Default
         {
-            get => _schemaReferenceInfo.Default ?? Target?.Default;
-            set => _schemaReferenceInfo.Default = value;
+            get => Reference.Default ?? Target?.Default;
+            set => Reference.Default = value;
         }
         /// <inheritdoc/>
         public bool ReadOnly
         {
-            get => _schemaReferenceInfo.ReadOnly ?? Target?.ReadOnly ?? false;
-            set => _schemaReferenceInfo.ReadOnly = value;
+            get => Reference.ReadOnly ?? Target?.ReadOnly ?? false;
+            set => Reference.ReadOnly = value;
         }
         /// <inheritdoc/>
         public bool WriteOnly
         {
-            get => _schemaReferenceInfo.WriteOnly ?? Target?.WriteOnly ?? false;
-            set => _schemaReferenceInfo.WriteOnly = value;
+            get => Reference.WriteOnly ?? Target?.WriteOnly ?? false;
+            set => Reference.WriteOnly = value;
         }
         /// <inheritdoc/>
         public IList<IOpenApiSchema>? AllOf { get => Target?.AllOf; }
@@ -161,8 +138,8 @@ public bool WriteOnly
         /// <inheritdoc/>
         public IList<JsonNode>? Examples
         {
-            get => _schemaReferenceInfo.Examples ?? Target?.Examples;
-            set => _schemaReferenceInfo.Examples = value;
+            get => Reference.Examples ?? Target?.Examples;
+            set => Reference.Examples = value;
         }
         /// <inheritdoc/>
         public IList<JsonNode>? Enum { get => Target?.Enum; }
@@ -173,8 +150,8 @@ public IList<JsonNode>? Examples
         /// <inheritdoc/>
         public bool Deprecated
         {
-            get => _schemaReferenceInfo.Deprecated ?? Target?.Deprecated ?? false;
-            set => _schemaReferenceInfo.Deprecated = value;
+            get => Reference.Deprecated ?? Target?.Deprecated ?? false;
+            set => Reference.Deprecated = value;
         }
         /// <inheritdoc/>
         public OpenApiXml? Xml { get => Target?.Xml; }
@@ -196,7 +173,7 @@ public override void SerializeAsV31(IOpenApiWriter writer)
                 {
                     CopyReferenceAsTargetElementWithOverrides(s).SerializeAsV31(w);
                 }
-                else if (element is OpenApiSchemaReferenceInformation schemaRefInfo)
+                else if (element is JsonSchemaReference schemaRefInfo)
                 {
                     schemaRefInfo.SerializeAsV31(w);
                 }
@@ -219,15 +196,15 @@ public override void SerializeAsV2(IOpenApiWriter writer)
         }
         private void SerializeAsWithoutLoops(IOpenApiWriter writer, Action<IOpenApiWriter, IOpenApiSerializable> action)
         {
-            if (!writer.GetSettings().ShouldInlineReference(_schemaReferenceInfo))
+            if (!writer.GetSettings().ShouldInlineReference(Reference))
             {
-                action(writer, _schemaReferenceInfo);
+                action(writer, Reference);
             }
             // If Loop is detected then just Serialize as a reference.
             else if (!writer.GetSettings().LoopDetector.PushLoop<IOpenApiSchema>(this))
             {
                 writer.GetSettings().LoopDetector.SaveLoop<IOpenApiSchema>(this);
-                action(writer, _schemaReferenceInfo);
+                action(writer, Reference);
             }
             else
             {
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiSecuritySchemeReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiSecuritySchemeReference.cs
@@ -9,8 +9,8 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Security Scheme Object Reference.
     /// </summary>
-    public class OpenApiSecuritySchemeReference : BaseOpenApiReferenceHolder<OpenApiSecurityScheme, IOpenApiSecurityScheme>, IOpenApiSecurityScheme
-    {
+    public class OpenApiSecuritySchemeReference : BaseOpenApiReferenceHolder<OpenApiSecurityScheme, IOpenApiSecurityScheme, OpenApiReference>, IOpenApiSecurityScheme
+    { //TODO switch to the non summary version
         /// <summary>
         /// Constructor initializing the reference object.
         /// </summary>
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiTagReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiTagReference.cs
@@ -9,8 +9,8 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Tag Object Reference
     /// </summary>
-    public class OpenApiTagReference : BaseOpenApiReferenceHolder<OpenApiTag, IOpenApiTag>, IOpenApiTag
-    {
+    public class OpenApiTagReference : BaseOpenApiReferenceHolder<OpenApiTag, IOpenApiTag, OpenApiReference>, IOpenApiTag
+    {//TODO switch to a reference kind that does not support additional fields
         /// <summary>
         /// Resolved target of the reference.
         /// </summary>

Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi`
`8`	`8`	`/// <summary>`
`9`	`9`	`/// Callback Object Reference: A reference to a map of possible out-of band callbacks related to the parent operation.`
`10`	`10`	`/// </summary>`
`11`		`- public class OpenApiCallbackReference : BaseOpenApiReferenceHolder<OpenApiCallback, IOpenApiCallback>, IOpenApiCallback`
	`11`	`+ public class OpenApiCallbackReference : BaseOpenApiReferenceHolder<OpenApiCallback, IOpenApiCallback, OpenApiReference>, IOpenApiCallback`
`12`	`12`	`{`
`13`	`13`	`/// <summary>`
`14`	`14`	`/// Constructor initializing the reference object.`
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi`
`9`	`9`	`/// <summary>`
`10`	`10`	`/// Example Object Reference.`
`11`	`11`	`/// </summary>`
`12`		`- public class OpenApiExampleReference : BaseOpenApiReferenceHolder<OpenApiExample, IOpenApiExample>, IOpenApiExample`
	`12`	`+ public class OpenApiExampleReference : BaseOpenApiReferenceHolder<OpenApiExample, IOpenApiExample, OpenApiReference>, IOpenApiExample`
`13`	`13`	`{`
`14`	`14`	`/// <summary>`
`15`	`15`	`/// Constructor initializing the reference object.`