Merge pull request #2091 from microsoft/fix/headers-reference

fix/headers reference

Author: baywet

src/Microsoft.OpenApi.Hidi/StatsVisitor.cs

@@ -27,7 +27,7 @@ public override void Visit(OpenApiSchema schema)
 
         public int HeaderCount { get; set; }
 
-        public override void Visit(IDictionary<string, OpenApiHeader> headers)
+        public override void Visit(IDictionary<string, IOpenApiHeader> headers)
         {
             HeaderCount++;
         }

src/Microsoft.OpenApi.Workbench/StatsVisitor.cs

@@ -27,7 +27,7 @@ public override void Visit(OpenApiSchema schema)
 
         public int HeaderCount { get; set; }
 
-        public override void Visit(IDictionary<string, OpenApiHeader> headers)
+        public override void Visit(IDictionary<string, IOpenApiHeader> headers)
         {
             HeaderCount++;
         }

src/Microsoft.OpenApi/Extensions/OpenApiReferencableExtensions.cs

@@ -92,15 +92,24 @@ private static IOpenApiReferenceable ResolveReferenceOnResponseElement(
             string mapKey,
             JsonPointer pointer)
         {
-            switch (propertyName)
+            if (!string.IsNullOrEmpty(mapKey))
             {
-                case OpenApiConstants.Headers when mapKey != null:
-                    return responseElement.Headers[mapKey];
-                case OpenApiConstants.Links when mapKey != null:
-                    return responseElement.Links[mapKey];
-                default:
-                    throw new OpenApiException(string.Format(SRResource.InvalidReferenceId, pointer));
+                if (OpenApiConstants.Headers.Equals(propertyName, StringComparison.Ordinal) &&
+                    responseElement?.Headers != null &&
+                    responseElement.Headers.TryGetValue(mapKey, out var headerElement) &&
+                    headerElement is IOpenApiReferenceable referenceable)
+                {
+                    return referenceable;
+                }
+                if (OpenApiConstants.Links.Equals(propertyName, StringComparison.Ordinal) &&
+                    responseElement?.Links != null &&
+                    responseElement.Links.TryGetValue(mapKey, out var linkElement) &&
+                    linkElement is IOpenApiReferenceable referenceable2)
+                {
+                    return referenceable2;
+                }
             }
+            throw new OpenApiException(string.Format(SRResource.InvalidReferenceId, pointer));
         }
     }
 }

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

@@ -3,15 +3,10 @@
 namespace Microsoft.OpenApi.Models.Interfaces;
 
 /// <summary>
-/// Describes an element that has a summary and description.
+/// Describes an element that has a description.
 /// </summary>
 public interface IOpenApiDescribedElement : IOpenApiElement
 {
-    /// <summary>
-    /// Short description for the example.
-    /// </summary>
-    public string Summary { get; set; }
-
     /// <summary>
     /// Long description for the example.
     /// CommonMark syntax MAY be used for rich text representation.

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, IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiExample : IOpenApiDescribedElement, IOpenApiSummarizedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible
 {
     /// <summary>
     /// Embedded literal example. The value field and externalValue field are mutually

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

@@ -0,0 +1,65 @@
+
+using System.Collections.Generic;
+using System.Text.Json.Nodes;
+using Microsoft.OpenApi.Interfaces;
+
+namespace Microsoft.OpenApi.Models.Interfaces;
+
+/// <summary>
+/// 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
+{
+    /// <summary>
+    /// Determines whether this header is mandatory.
+    /// </summary>
+    public bool Required { get; }
+
+    /// <summary>
+    /// Specifies that a header is deprecated and SHOULD be transitioned out of usage.
+    /// </summary>
+    public bool Deprecated { get; }
+
+    /// <summary>
+    /// Sets the ability to pass empty-valued headers.
+    /// </summary>
+    public bool AllowEmptyValue { get; }
+
+    /// <summary>
+    /// Describes how the header value will be serialized depending on the type of the header value.
+    /// </summary>
+    public ParameterStyle? Style { get; }
+
+    /// <summary>
+    /// When this is true, header values of type array or object generate separate parameters
+    /// for each value of the array or key-value pair of the map.
+    /// </summary>
+    public bool Explode { get; }
+
+    /// <summary>
+    /// Determines whether the header value SHOULD allow reserved characters, as defined by RFC3986.
+    /// </summary>
+    public bool AllowReserved { get; }
+
+    /// <summary>
+    /// The schema defining the type used for the request body.
+    /// </summary>
+    public OpenApiSchema Schema { get; }
+
+    /// <summary>
+    /// Example of the media type.
+    /// </summary>
+    public JsonNode Example { get; }
+
+    /// <summary>
+    /// Examples of the media type.
+    /// </summary>
+    public IDictionary<string, IOpenApiExample> Examples { get; }
+
+    /// <summary>
+    /// A map containing the representations for the header.
+    /// </summary>
+    public IDictionary<string, OpenApiMediaType> Content { get; }
+
+}

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

@@ -0,0 +1,13 @@
+using Microsoft.OpenApi.Interfaces;
+
+namespace Microsoft.OpenApi.Models.Interfaces;
+/// <summary>
+/// Describes an element that has a summary.
+/// </summary>
+public interface IOpenApiSummarizedElement : IOpenApiElement
+{
+    /// <summary>
+    /// Short description for the example.
+    /// </summary>
+    public string Summary { get; set; }
+}

src/Microsoft.OpenApi/Models/OpenApiComponents.cs

@@ -45,9 +45,9 @@ public class OpenApiComponents : IOpenApiSerializable, IOpenApiExtensible
             new Dictionary<string, OpenApiRequestBody>();
 
         /// <summary>
-        /// An object to hold reusable <see cref="OpenApiHeader"/> Objects.
+        /// An object to hold reusable <see cref="IOpenApiHeader"/> Objects.
         /// </summary>
-        public IDictionary<string, OpenApiHeader>? Headers { get; set; } = new Dictionary<string, OpenApiHeader>();
+        public IDictionary<string, IOpenApiHeader>? Headers { get; set; } = new Dictionary<string, IOpenApiHeader>();
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiSecurityScheme"/> Objects.
@@ -90,7 +90,7 @@ public OpenApiComponents(OpenApiComponents? components)
             Parameters = components?.Parameters != null ? new Dictionary<string, OpenApiParameter>(components.Parameters) : null;
             Examples = components?.Examples != null ? new Dictionary<string, IOpenApiExample>(components.Examples) : null;
             RequestBodies = components?.RequestBodies != null ? new Dictionary<string, OpenApiRequestBody>(components.RequestBodies) : null;
-            Headers = components?.Headers != null ? new Dictionary<string, OpenApiHeader>(components.Headers) : null;
+            Headers = components?.Headers != null ? new Dictionary<string, IOpenApiHeader>(components.Headers) : null;
             SecuritySchemes = components?.SecuritySchemes != null ? new Dictionary<string, OpenApiSecurityScheme>(components.SecuritySchemes) : null;
             Links = components?.Links != null ? new Dictionary<string, OpenApiLink>(components.Links) : null;
             Callbacks = components?.Callbacks != null ? new Dictionary<string, IOpenApiCallback>(components.Callbacks) : null;

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -620,7 +620,7 @@ public bool AddComponent<T>(string id, T componentToRegister)
                     Components.Examples.Add(id, openApiExample);
                     break;
                 case OpenApiHeader openApiHeader:
-                    Components.Headers ??= new Dictionary<string, OpenApiHeader>();
+                    Components.Headers ??= new Dictionary<string, IOpenApiHeader>();
                     Components.Headers.Add(id, openApiHeader);
                     break;
                 case OpenApiSecurityScheme openApiSecurityScheme:

src/Microsoft.OpenApi/Models/OpenApiEncoding.cs

@@ -5,6 +5,7 @@
 using System.Collections.Generic;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Interfaces;
+using Microsoft.OpenApi.Models.Interfaces;
 using Microsoft.OpenApi.Writers;
 
 namespace Microsoft.OpenApi.Models
@@ -24,7 +25,7 @@ public class OpenApiEncoding : IOpenApiSerializable, IOpenApiExtensible
         /// <summary>
         /// A map allowing additional information to be provided as headers.
         /// </summary>
-        public IDictionary<string, OpenApiHeader> Headers { get; set; } = new Dictionary<string, OpenApiHeader>();
+        public IDictionary<string, IOpenApiHeader> Headers { get; set; } = new Dictionary<string, IOpenApiHeader>();
 
         /// <summary>
         /// Describes how a specific property value will be serialized depending on its type.
@@ -64,7 +65,7 @@ public OpenApiEncoding() { }
         public OpenApiEncoding(OpenApiEncoding encoding)
         {
             ContentType = encoding?.ContentType ?? ContentType;
-            Headers = encoding?.Headers != null ? new Dictionary<string, OpenApiHeader>(encoding.Headers) : null;
+            Headers = encoding?.Headers != null ? new Dictionary<string, IOpenApiHeader>(encoding.Headers) : null;
             Style = encoding?.Style ?? Style;
             Explode = encoding?.Explode ?? Explode;
             AllowReserved = encoding?.AllowReserved ?? AllowReserved;