Merge pull request #2699 from microsoft/feat/content-interface-to-v2

feat(models): add shared Content interface (#2695)

Author: baywet

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

@@ -0,0 +1,27 @@
+using System.Collections.Generic;
+
+namespace Microsoft.OpenApi;
+
+/// <summary>
+/// Describes an element that has content.
+/// </summary>
+public interface IOpenApiContentElement
+{
+    /// <summary>
+    /// A map containing descriptions of potential payloads.
+    /// The key is a media type or media type range and the value describes it.
+    /// </summary>
+    IDictionary<string, OpenApiMediaType>? Content { get; set; }
+}
+
+/// <summary>
+/// Describes an element that has content.
+/// </summary>
+public interface IOpenApiReadOnlyContentElement
+{
+    /// <summary>
+    /// A map containing descriptions of potential payloads.
+    /// The key is a media type or media type range and the value describes it.
+    /// </summary>
+    IDictionary<string, OpenApiMediaType>? Content { get; }
+}

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

@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi;
 /// 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, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiHeader>, IOpenApiReferenceable
+public interface IOpenApiHeader : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiHeader>, IOpenApiReferenceable, IOpenApiReadOnlyContentElement
 {
     /// <summary>
     /// Determines whether this header is mandatory.
@@ -57,10 +57,4 @@ public interface IOpenApiHeader : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// 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/IOpenApiParameter.cs

@@ -7,7 +7,7 @@ namespace Microsoft.OpenApi;
 /// 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, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiParameter>, IOpenApiReferenceable
+public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiParameter>, IOpenApiReferenceable, IOpenApiReadOnlyContentElement
 {
     /// <summary>
     /// REQUIRED. The name of the parameter. Parameter names are case sensitive.
@@ -93,15 +93,4 @@ public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiReadOnlyE
     /// Assign <see cref="JsonNullSentinel.JsonNull"/> to use get null as a serialized value.
     /// </summary>
     public JsonNode? Example { get; }
-
-    /// <summary>
-    /// A map containing the representations for the parameter.
-    /// The key is the media type and the value describes it.
-    /// The map MUST only contain one entry.
-    /// For more complex scenarios, the content property can define the media type and schema of the parameter.
-    /// A parameter MUST contain either a schema property, or a content property, but not both.
-    /// When example or examples are provided in conjunction with the schema object,
-    /// the example MUST follow the prescribed serialization strategy for the parameter.
-    /// </summary>
-    public IDictionary<string, OpenApiMediaType>? Content { get; }    
 }

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

@@ -6,18 +6,13 @@ namespace Microsoft.OpenApi;
 /// 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, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiRequestBody>, IOpenApiReferenceable
+public interface IOpenApiRequestBody : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiRequestBody>, IOpenApiReferenceable, IOpenApiReadOnlyContentElement
 {
     /// <summary>
     /// Determines if the request body is required in the request. Defaults to false.
     /// </summary>
     public bool Required { get; }
 
-    /// <summary>
-    /// REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it.
-    /// For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
-    /// </summary>
-    public IDictionary<string, OpenApiMediaType>? Content { get; }
     /// <summary>
     /// Converts the request body to a body parameter in preparation for a v2 serialization.
     /// </summary>

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

@@ -6,19 +6,13 @@ namespace Microsoft.OpenApi;
 /// 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, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiResponse>, IOpenApiReferenceable
+public interface IOpenApiResponse : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiResponse>, IOpenApiReferenceable, IOpenApiReadOnlyContentElement
 {
     /// <summary>
     /// Maps a header name to its definition.
     /// </summary>
     public IDictionary<string, IOpenApiHeader>? Headers { get; }
 
-    /// <summary>
-    /// A map containing descriptions of potential response payloads.
-    /// The key is a media type or media type range and the value describes it.
-    /// </summary>
-    public IDictionary<string, OpenApiMediaType>? Content { get; }
-
     /// <summary>
     /// A map of operations links that can be followed from the response.
     /// The key of the map is a short name for the link,

src/Microsoft.OpenApi/Models/OpenApiHeader.cs

@@ -11,7 +11,7 @@ namespace Microsoft.OpenApi
     /// Header Object.
     /// The Header Object follows the structure of the Parameter Object.
     /// </summary>
-    public class OpenApiHeader : IOpenApiHeader, IOpenApiExtensible
+    public class OpenApiHeader : IOpenApiHeader, IOpenApiExtensible, IOpenApiContentElement
     {
         /// <inheritdoc/>
         public string? Description { get; set; }
@@ -90,7 +90,7 @@ public virtual void SerializeAsV3(IOpenApiWriter writer)
             SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (writer, element) => element.SerializeAsV3(writer));
         }
 
-        internal void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version, 
+        internal void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version,
             Action<IOpenApiWriter, IOpenApiSerializable> callback)
         {
             Utils.CheckArgumentNull(writer);
@@ -167,7 +167,8 @@ public virtual void SerializeAsV2(IOpenApiWriter writer)
             writer.WriteProperty(OpenApiConstants.AllowReserved, AllowReserved, false);
 
             // schema
-            var targetSchema = Schema switch {
+            var targetSchema = Schema switch
+            {
                 OpenApiSchemaReference schemaReference => schemaReference.RecursiveTarget,
                 OpenApiSchema schema => schema,
                 _ => null,

src/Microsoft.OpenApi/Models/OpenApiParameter.cs

@@ -11,7 +11,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Parameter Object.
     /// </summary>
-    public class OpenApiParameter : IOpenApiExtensible, IOpenApiParameter
+    public class OpenApiParameter : IOpenApiExtensible, IOpenApiParameter, IOpenApiContentElement
     {
         private bool? _explode;
         private ParameterStyle? _style;
@@ -60,7 +60,15 @@ public bool Explode
         /// <inheritdoc/>
         public JsonNode? Example { get; set; }
 
-        /// <inheritdoc/>
+        /// <summary>
+        /// A map containing the representations for the parameter.
+        /// The key is the media type and the value describes it.
+        /// The map MUST only contain one entry.
+        /// For more complex scenarios, the content property can define the media type and schema of the parameter.
+        /// A parameter MUST contain either a schema property, or a content property, but not both.
+        /// When example or examples are provided in conjunction with the schema object,
+        /// the example MUST follow the prescribed serialization strategy for the parameter.
+        /// </summary>
         public IDictionary<string, OpenApiMediaType>? Content { get; set; }
 
         /// <inheritdoc/>
@@ -105,7 +113,7 @@ public virtual void SerializeAsV3(IOpenApiWriter writer)
             SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (writer, element) => element.SerializeAsV3(writer));
         }
 
-        internal void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version, 
+        internal void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version,
             Action<IOpenApiWriter, IOpenApiSerializable> callback)
         {
             Utils.CheckArgumentNull(writer);
@@ -200,7 +208,8 @@ internal virtual void WriteRequestBodySchemaForV2(IOpenApiWriter writer, Diction
                 // uniqueItems
                 // enum
                 // multipleOf
-                var targetSchema = Schema switch {
+                var targetSchema = Schema switch
+                {
                     OpenApiSchemaReference schemaReference => schemaReference.RecursiveTarget,
                     OpenApiSchema schema => schema,
                     _ => null,

src/Microsoft.OpenApi/Models/OpenApiRequestBody.cs

@@ -10,15 +10,18 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Request Body Object
     /// </summary>
-    public class OpenApiRequestBody : IOpenApiExtensible, IOpenApiRequestBody
+    public class OpenApiRequestBody : IOpenApiExtensible, IOpenApiRequestBody, IOpenApiContentElement
     {
         /// <inheritdoc />
         public string? Description { get; set; }
 
         /// <inheritdoc />
         public bool Required { get; set; }
 
-        /// <inheritdoc />
+        /// <summary>
+        /// REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it.
+        /// For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+        /// </summary>
         public IDictionary<string, OpenApiMediaType>? Content { get; set; }
 
         /// <inheritdoc />
@@ -56,7 +59,7 @@ public virtual void SerializeAsV3(IOpenApiWriter writer)
         {
             SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (writer, element) => element.SerializeAsV3(writer));
         }
-        
+
         internal void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version,
             Action<IOpenApiWriter, IOpenApiSerializable> callback)
         {
@@ -102,7 +105,7 @@ public IOpenApiParameter ConvertToBodyParameter(IOpenApiWriter writer)
                 Extensions = Extensions?.ToDictionary(static k => k.Key, static v => v.Value)
             };
             // Clone extensions so we can remove the x-bodyName extensions from the output V2 model.
-            if (bodyParameter.Extensions is not null && 
+            if (bodyParameter.Extensions is not null &&
                 bodyParameter.Extensions.TryGetValue(OpenApiConstants.BodyName, out var bodyNameExtension) &&
                 bodyNameExtension is JsonNodeExtension bodyName)
             {
@@ -118,7 +121,7 @@ public IEnumerable<IOpenApiParameter> ConvertToFormDataParameters(IOpenApiWriter
             if (Content == null || !Content.Any())
                 yield break;
             var properties = Content.First().Value.Schema?.Properties;
-            if(properties != null)
+            if (properties != null)
             {
                 foreach (var property in properties)
                 {
@@ -136,11 +139,11 @@ public IEnumerable<IOpenApiParameter> ConvertToFormDataParameters(IOpenApiWriter
                             OpenApiSchemaReference => throw new InvalidOperationException("Unresolved reference target"),
                             _ => throw new InvalidOperationException("Unexpected schema type")
                         };
-                        
+
                         updatedSchema.Type = "file".ToJsonSchemaType();
                         updatedSchema.Format = null;
                         paramSchema = updatedSchema;
-                        
+
                     }
                     yield return new OpenApiFormDataParameter()
                     {
@@ -151,7 +154,7 @@ public IEnumerable<IOpenApiParameter> ConvertToFormDataParameters(IOpenApiWriter
                         Required = Content.First().Value.Schema?.Required?.Contains(property.Key) ?? false
                     };
                 }
-            }            
+            }
         }
 
         /// <inheritdoc/>

src/Microsoft.OpenApi/Models/OpenApiResponse.cs

@@ -10,7 +10,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Response object.
     /// </summary>
-    public class OpenApiResponse : IOpenApiExtensible, IOpenApiResponse
+    public class OpenApiResponse : IOpenApiExtensible, IOpenApiResponse, IOpenApiContentElement
     {
         /// <inheritdoc/>
         public string? Description { get; set; }
@@ -61,7 +61,7 @@ public virtual void SerializeAsV3(IOpenApiWriter writer)
             SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (writer, element) => element.SerializeAsV3(writer));
         }
 
-        private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version, 
+        private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version,
             Action<IOpenApiWriter, IOpenApiSerializable> callback)
         {
             Utils.CheckArgumentNull(writer);
@@ -153,7 +153,7 @@ public virtual void SerializeAsV2(IOpenApiWriter writer)
                             // so remove it from the cloned collection so we don't write it again.
                             extensionsClone?.Remove(key);
                         }
-                    }                    
+                    }
                 }
             }