Merge pull request #2708 from microsoft/fix/missing-method-v3

fix: broken binary compatibility due to interface changes in previous version
Release-As: 3.3.1

Author: baywet

CHANGELOG.md

@@ -87,29 +87,6 @@
 
 * adds support for OpenAPI 3.2.0 ([765a8dd](https://github.com/microsoft/OpenAPI.NET/commit/765a8dd4d6efd1a31b6a76d282ccffa5877a845a))
 
-## [2.6.0](https://github.com/microsoft/OpenAPI.NET/compare/v2.5.0...v2.6.0) (2026-01-21)
-
-### Features
-
-* **models:** add shared Content interface ([80e4bbf](https://github.com/microsoft/OpenAPI.NET/commit/80e4bbfa4ab31d3af69fe29751714d001c1f9566))
-* **models:** add shared Content interface ([#2695](https://github.com/microsoft/OpenAPI.NET/issues/2695)) ([338566f](https://github.com/microsoft/OpenAPI.NET/commit/338566fafce04ee1329f4ead61fe1e87e01144ad))
-* **models:** add shared Content interface ([#2695](https://github.com/microsoft/OpenAPI.NET/issues/2695)) ([80e4bbf](https://github.com/microsoft/OpenAPI.NET/commit/80e4bbfa4ab31d3af69fe29751714d001c1f9566))
-* **models:** support mutualTLS security scheme ([f9cf5b8](https://github.com/microsoft/OpenAPI.NET/commit/f9cf5b807d71c49e5bd7e2bec97f12d3b50ca180))
-
-## [2.5.0](https://github.com/microsoft/OpenAPI.NET/compare/v2.4.3...v2.5.0) (2026-01-19)
-
-## Features
-
-* hidi validate command now logs warnings ([1d3d085](https://github.com/microsoft/OpenAPI.NET/commit/1d3d085e0278d9341d7bd10065eba584cb25773c))
-* hidi validate command now logs warnings ([18ed5ac](https://github.com/microsoft/OpenAPI.NET/commit/18ed5acce9661639e1698f19c194e520eb5c93c1))
-
-
-### Bug Fixes
-
-* discriminator property validation fails any/allOf cases when it shouldn't ([ff6e411](https://github.com/microsoft/OpenAPI.NET/commit/ff6e4115dcab8c893bbc6b97639fd620b50f105e))
-* discriminator property validation fails any/allOf cases when it shouldn't ([7def73d](https://github.com/microsoft/OpenAPI.NET/commit/7def73d774d1f0e96118e92b636e52cbea371f2d))
-
-
 ## [2.4.3](https://github.com/microsoft/OpenAPI.NET/compare/v2.4.2...v2.4.3) (2026-01-16)
 
 ## Bug Fixes

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiContentElement.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, IOpenApiReadOnlyContentElement
+public interface IOpenApiHeader : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiHeader>, IOpenApiReferenceable
 {
     /// <summary>
     /// Determines whether this header is mandatory.
@@ -57,4 +57,10 @@ 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, IOpenApiMediaType>? Content { get; }
+
 }

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiHeader.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, IOpenApiReadOnlyContentElement
+public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiParameter>, IOpenApiReferenceable
 {
     /// <summary>
     /// REQUIRED. The name of the parameter. Parameter names are case sensitive.
@@ -93,4 +93,15 @@ 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, IOpenApiMediaType>? Content { get; }    
 }

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

@@ -6,13 +6,18 @@ 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, IOpenApiReadOnlyContentElement
+public interface IOpenApiRequestBody : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiRequestBody>, IOpenApiReferenceable
 {
     /// <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, IOpenApiMediaType>? Content { get; }
     /// <summary>
     /// Converts the request body to a body parameter in preparation for a v2 serialization.
     /// </summary>

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

@@ -6,13 +6,19 @@ 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, IOpenApiSummarizedElement, IOpenApiReadOnlyContentElement
+public interface IOpenApiResponse : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiResponse>, IOpenApiReferenceable, IOpenApiSummarizedElement
 {
     /// <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, IOpenApiMediaType>? 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/Interfaces/IOpenApiResponse.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, IOpenApiContentElement
+    public class OpenApiHeader : IOpenApiHeader, IOpenApiExtensible
     {
         /// <inheritdoc/>
         public string? Description { get; set; }
@@ -98,7 +98,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);
@@ -175,8 +175,7 @@ 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/OpenApiHeader.cs

@@ -11,7 +11,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Parameter Object.
     /// </summary>
-    public class OpenApiParameter : IOpenApiExtensible, IOpenApiParameter, IOpenApiContentElement
+    public class OpenApiParameter : IOpenApiExtensible, IOpenApiParameter
     {
         private bool? _explode;
         private ParameterStyle? _style;
@@ -60,15 +60,7 @@ public bool Explode
         /// <inheritdoc/>
         public JsonNode? Example { get; set; }
 
-        /// <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>
+        /// <inheritdoc/>
         public IDictionary<string, IOpenApiMediaType>? Content { get; set; }
 
         /// <inheritdoc/>
@@ -119,11 +111,11 @@ 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);
-
+            
             // Validate that Cookie style is only used in OpenAPI 3.2 and later
             if (Style == ParameterStyle.Cookie && version < OpenApiSpecVersion.OpenApi3_2)
             {
@@ -234,8 +226,7 @@ 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,
@@ -280,7 +271,7 @@ internal virtual void WriteRequestBodySchemaForV2(IOpenApiWriter writer, Diction
         public virtual void SerializeAsV2(IOpenApiWriter writer)
         {
             Utils.CheckArgumentNull(writer);
-
+            
             // Validate that Cookie style is only used in OpenAPI 3.2 and later
             if (Style == ParameterStyle.Cookie)
             {

src/Microsoft.OpenApi/Models/OpenApiParameter.cs

@@ -10,18 +10,15 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Request Body Object
     /// </summary>
-    public class OpenApiRequestBody : IOpenApiExtensible, IOpenApiRequestBody, IOpenApiContentElement
+    public class OpenApiRequestBody : IOpenApiExtensible, IOpenApiRequestBody
     {
         /// <inheritdoc />
         public string? Description { get; set; }
 
         /// <inheritdoc />
         public bool Required { get; set; }
 
-        /// <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>
+        /// <inheritdoc />
         public IDictionary<string, IOpenApiMediaType>? Content { get; set; }
 
         /// <inheritdoc />
@@ -67,7 +64,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)
         {
@@ -113,7 +110,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)
             {
@@ -129,7 +126,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)
                 {
@@ -147,11 +144,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()
                     {
@@ -162,7 +159,7 @@ public IEnumerable<IOpenApiParameter> ConvertToFormDataParameters(IOpenApiWriter
                         Required = Content.First().Value.Schema?.Required?.Contains(property.Key) ?? false
                     };
                 }
-            }
+            }            
         }
 
         /// <inheritdoc/>

src/Microsoft.OpenApi/Models/OpenApiRequestBody.cs

@@ -10,7 +10,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Response object.
     /// </summary>
-    public class OpenApiResponse : IOpenApiExtensible, IOpenApiResponse, IOpenApiContentElement
+    public class OpenApiResponse : IOpenApiExtensible, IOpenApiResponse
     {
         /// <inheritdoc/>
         public string? Summary { get; set; }
@@ -73,7 +73,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);
@@ -177,7 +177,7 @@ public virtual void SerializeAsV2(IOpenApiWriter writer)
                             // so remove it from the cloned collection so we don't write it again.
                             extensionsClone?.Remove(key);
                         }
-                    }
+                    }                    
                 }
             }