fix: removes description field from references that do not support it

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

Author: baywet

src/Microsoft.OpenApi/Models/OpenApiReference.cs renamed to src/Microsoft.OpenApi/Models/BaseOpenApiReference.cs

@@ -11,17 +11,8 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// A simple object to allow referencing other components in the specification, internally and externally.
     /// </summary>
-    public class BaseOpenApiReference : IOpenApiSerializable, IOpenApiDescribedElement
+    public class BaseOpenApiReference : IOpenApiSerializable
     {
-        /// <summary>
-        /// A description which by default SHOULD override that of the referenced component.
-        /// CommonMark syntax MAY be used for rich text representation.
-        /// If the referenced object-type does not allow a description field, then this field has no effect.
-        /// </summary>
-        public string? Description { get; set; }
-
-
-
         /// <summary>
         /// External resource in the reference.
         /// It maybe:
@@ -147,7 +138,6 @@ public BaseOpenApiReference() { }
         public BaseOpenApiReference(BaseOpenApiReference reference)
         {
             Utils.CheckArgumentNull(reference);
-            Description = reference.Description;
             ExternalResource = reference.ExternalResource;
             Type = reference.Type;
             Id = reference.Id;
@@ -166,8 +156,7 @@ public virtual void SerializeAsV31(IOpenApiWriter writer)
         /// <param name="writer"></param>
         protected virtual void SerializeAdditionalV31Properties(IOpenApiWriter writer)
         {
-            // summary and description are in 3.1 but not in 3.0
-            writer.WriteProperty(OpenApiConstants.Description, Description);
+            // noop for the base type
         }
 
         /// <inheritdoc/>
@@ -305,13 +294,7 @@ internal virtual void SetMetadataFromMapNode(MapNode mapNode)
         /// <param name="jsonObject">The object to get the data from</param>
         protected virtual void SetAdditional31MetadataFromMapNode(JsonObject jsonObject)
         {
-            // Summary and Description
-            var description = GetPropertyValueFromNode(jsonObject, OpenApiConstants.Description);
-
-            if (!string.IsNullOrEmpty(description))
-            {
-                Description = description;
-            }
+            // noop for the base type
         }
 
         internal void SetJsonPointerPath(string pointer, string nodeLocation)

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 JsonSchemaReference : BaseOpenApiReference
+public class JsonSchemaReference : OpenApiReferenceWithDescription
 {
     /// <summary>
     /// A default value which by default SHOULD override that of the referenced component.

src/Microsoft.OpenApi/Models/OpenApiReferenceWithDescription.cs

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using System.Text.Json.Nodes;
+
+namespace Microsoft.OpenApi;
+
+/// <summary>
+/// OpenApiReferenceWithSummary is a reference to an OpenAPI component that includes a description.
+/// </summary>
+public class OpenApiReferenceWithDescription : BaseOpenApiReference, IOpenApiDescribedElement
+{
+    /// <summary>
+    /// A description which by default SHOULD override that of the referenced component.
+    /// CommonMark syntax MAY be used for rich text representation.
+    /// If the referenced object-type does not allow a description field, then this field has no effect.
+    /// </summary>
+    public string? Description { get; set; }
+
+    /// <summary>
+    /// Parameterless constructor
+    /// </summary>
+    public OpenApiReferenceWithDescription() : base() { }
+
+    /// <summary>
+    /// Initializes a copy instance of the <see cref="OpenApiReferenceWithDescription"/> object
+    /// </summary>
+    public OpenApiReferenceWithDescription(OpenApiReferenceWithDescription reference) : base(reference)
+    {
+        Utils.CheckArgumentNull(reference);
+        Description = reference.Description;
+    }
+    /// <inheritdoc/>
+    protected override void SerializeAdditionalV31Properties(IOpenApiWriter writer)
+    {
+        base.SerializeAdditionalV31Properties(writer);
+        // summary and description are in 3.1 but not in 3.0
+        writer.WriteProperty(OpenApiConstants.Description, Description);
+    }
+    /// <inheritdoc/>
+    protected override void SetAdditional31MetadataFromMapNode(JsonObject jsonObject)
+    {
+        base.SetAdditional31MetadataFromMapNode(jsonObject);
+        // Description
+        var description = GetPropertyValueFromNode(jsonObject, OpenApiConstants.Description);
+
+        if (!string.IsNullOrEmpty(description))
+        {
+            Description = description;
+        }
+    }
+}

src/Microsoft.OpenApi/Models/OpenApiReferenceWithSummary.cs renamed to src/Microsoft.OpenApi/Models/OpenApiReferenceWithDescriptionAndSummary.cs

@@ -1,17 +1,14 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
-using System;
-using System.Linq;
 using System.Text.Json.Nodes;
-using Microsoft.OpenApi.Reader;
 
 namespace Microsoft.OpenApi;
 
 /// <summary>
 /// OpenApiReferenceWithSummary is a reference to an OpenAPI component that includes a summary.
 /// </summary>
-public class OpenApiReferenceWithSummary : BaseOpenApiReference, IOpenApiSummarizedElement
+public class OpenApiReferenceWithDescriptionAndSummary : OpenApiReferenceWithDescription, IOpenApiSummarizedElement
 {
     /// <summary>
     /// A short summary which by default SHOULD override that of the referenced component.
@@ -22,12 +19,12 @@ public class OpenApiReferenceWithSummary : BaseOpenApiReference, IOpenApiSummari
     /// <summary>
     /// Parameterless constructor
     /// </summary>
-    public OpenApiReferenceWithSummary() : base() { }
+    public OpenApiReferenceWithDescriptionAndSummary() : base() { }
 
     /// <summary>
-    /// Initializes a copy instance of the <see cref="OpenApiReferenceWithSummary"/> object
+    /// Initializes a copy instance of the <see cref="OpenApiReferenceWithDescriptionAndSummary"/> object
     /// </summary>
-    public OpenApiReferenceWithSummary(OpenApiReferenceWithSummary reference) : base(reference)
+    public OpenApiReferenceWithDescriptionAndSummary(OpenApiReferenceWithDescriptionAndSummary reference) : base(reference)
     {
         Utils.CheckArgumentNull(reference);
         Summary = reference.Summary;
@@ -43,7 +40,7 @@ protected override void SerializeAdditionalV31Properties(IOpenApiWriter writer)
     protected override void SetAdditional31MetadataFromMapNode(JsonObject jsonObject)
     {
         base.SetAdditional31MetadataFromMapNode(jsonObject);
-        // Summary and Description
+        // Summary
         var summary = GetPropertyValueFromNode(jsonObject, OpenApiConstants.Summary);
 
         if (!string.IsNullOrEmpty(summary))

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, OpenApiReferenceWithSummary>, IOpenApiExample
+    public class OpenApiExampleReference : BaseOpenApiReferenceHolder<OpenApiExample, IOpenApiExample, OpenApiReferenceWithDescriptionAndSummary>, IOpenApiExample
     {
         /// <summary>
         /// Constructor initializing the reference object.
@@ -74,9 +74,9 @@ public IOpenApiExample CreateShallowCopy()
             return new OpenApiExampleReference(this);
         }
         /// <inheritdoc/>
-        protected override OpenApiReferenceWithSummary CopyReference(OpenApiReferenceWithSummary sourceReference)
+        protected override OpenApiReferenceWithDescriptionAndSummary CopyReference(OpenApiReferenceWithDescriptionAndSummary sourceReference)
         {
-            return new OpenApiReferenceWithSummary(sourceReference);
+            return new OpenApiReferenceWithDescriptionAndSummary(sourceReference);
         }
     }
 }

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

@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Header Object Reference.
     /// </summary>
-    public class OpenApiHeaderReference : BaseOpenApiReferenceHolder<OpenApiHeader, IOpenApiHeader, BaseOpenApiReference>, IOpenApiHeader
+    public class OpenApiHeaderReference : BaseOpenApiReferenceHolder<OpenApiHeader, IOpenApiHeader, OpenApiReferenceWithDescription>, IOpenApiHeader
     {
         /// <summary>
         /// Constructor initializing the reference object.
@@ -85,9 +85,9 @@ public IOpenApiHeader CreateShallowCopy()
             return new OpenApiHeaderReference(this);
         }
         /// <inheritdoc/>
-        protected override BaseOpenApiReference CopyReference(BaseOpenApiReference sourceReference)
+        protected override OpenApiReferenceWithDescription CopyReference(OpenApiReferenceWithDescription sourceReference)
         {
-            return new BaseOpenApiReference(sourceReference);
+            return new OpenApiReferenceWithDescription(sourceReference);
         }
     }
 }

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

@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Link Object Reference.
     /// </summary>
-    public class OpenApiLinkReference : BaseOpenApiReferenceHolder<OpenApiLink, IOpenApiLink, BaseOpenApiReference>, IOpenApiLink
+    public class OpenApiLinkReference : BaseOpenApiReferenceHolder<OpenApiLink, IOpenApiLink, OpenApiReferenceWithDescription>, IOpenApiLink
     {
         /// <summary>
         /// Constructor initializing the reference object.
@@ -74,9 +74,9 @@ public IOpenApiLink CreateShallowCopy()
             return new OpenApiLinkReference(this);
         }
         /// <inheritdoc/>
-        protected override BaseOpenApiReference CopyReference(BaseOpenApiReference sourceReference)
+        protected override OpenApiReferenceWithDescription CopyReference(OpenApiReferenceWithDescription sourceReference)
         {
-            return new BaseOpenApiReference(sourceReference);
+            return new OpenApiReferenceWithDescription(sourceReference);
         }
     }
 }

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

@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Parameter Object Reference.
     /// </summary>
-    public class OpenApiParameterReference : BaseOpenApiReferenceHolder<OpenApiParameter, IOpenApiParameter, BaseOpenApiReference>, IOpenApiParameter
+    public class OpenApiParameterReference : BaseOpenApiReferenceHolder<OpenApiParameter, IOpenApiParameter, OpenApiReferenceWithDescription>, IOpenApiParameter
     {
         /// <summary>
         /// Constructor initializing the reference object.
@@ -92,9 +92,9 @@ public IOpenApiParameter CreateShallowCopy()
         }
 
         /// <inheritdoc/>
-        protected override BaseOpenApiReference CopyReference(BaseOpenApiReference sourceReference)
+        protected override OpenApiReferenceWithDescription CopyReference(OpenApiReferenceWithDescription sourceReference)
         {
-            return new BaseOpenApiReference(sourceReference);
+            return new OpenApiReferenceWithDescription(sourceReference);
         }
     }
 }

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, OpenApiReferenceWithSummary>, IOpenApiPathItem
+    public class OpenApiPathItemReference : BaseOpenApiReferenceHolder<OpenApiPathItem, IOpenApiPathItem, OpenApiReferenceWithDescriptionAndSummary>, IOpenApiPathItem
     {
 
         /// <summary>
@@ -79,9 +79,9 @@ public override void SerializeAsV2(IOpenApiWriter writer)
             Reference.SerializeAsV2(writer);
         }
         /// <inheritdoc/>
-        protected override OpenApiReferenceWithSummary CopyReference(OpenApiReferenceWithSummary sourceReference)
+        protected override OpenApiReferenceWithDescriptionAndSummary CopyReference(OpenApiReferenceWithDescriptionAndSummary sourceReference)
         {
-            return new OpenApiReferenceWithSummary(sourceReference);
+            return new OpenApiReferenceWithDescriptionAndSummary(sourceReference);
         }
     }
 }

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

@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Request Body Object Reference.
     /// </summary>
-    public class OpenApiRequestBodyReference : BaseOpenApiReferenceHolder<OpenApiRequestBody, IOpenApiRequestBody, BaseOpenApiReference>, IOpenApiRequestBody
+    public class OpenApiRequestBodyReference : BaseOpenApiReferenceHolder<OpenApiRequestBody, IOpenApiRequestBody, OpenApiReferenceWithDescription>, IOpenApiRequestBody
     {
         /// <summary>
         /// Constructor initializing the reference object.
@@ -89,9 +89,9 @@ public IOpenApiRequestBody CreateShallowCopy()
             return new OpenApiRequestBodyReference(this);
         }
         /// <inheritdoc/>
-        protected override BaseOpenApiReference CopyReference(BaseOpenApiReference sourceReference)
+        protected override OpenApiReferenceWithDescription CopyReference(OpenApiReferenceWithDescription sourceReference)
         {
-            return new BaseOpenApiReference(sourceReference);
+            return new OpenApiReferenceWithDescription(sourceReference);
         }
     }
 }