add new v32 properties for Path Items

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

@@ -1,5 +1,4 @@
-
-using System.Collections.Generic;
+using System.Collections.Generic;
 using System.Net.Http;
 
 namespace Microsoft.OpenApi;
@@ -25,4 +24,15 @@ public interface IOpenApiPathItem : IOpenApiDescribedElement, IOpenApiSummarized
     /// These parameters can be overridden at the operation level, but cannot be removed there.
     /// </summary>
     public IList<IOpenApiParameter>? Parameters { get; }
+
+    /// <summary>
+    /// Gets the query operation for this path (OpenAPI 3.2).
+    /// </summary>
+    public OpenApiOperation? Query { get; }
+
+    /// <summary>
+    /// Gets the additional operations for this path (OpenAPI 3.2).
+    /// A map of additional operations that are not one of the standard HTTP methods (GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH, TRACE).
+    /// </summary>
+    public IDictionary<string, OpenApiOperation>? AdditionalOperations { get; }
 }

src/Microsoft.OpenApi/Models/OpenApiConstants.cs

@@ -205,6 +205,16 @@ public static class OpenApiConstants
         /// </summary>
         public const string RequestBody = "requestBody";
 
+        /// <summary>
+        /// Field: Query (OpenAPI 3.2)
+        /// </summary>
+        public const string Query = "query";
+
+        /// <summary>
+        /// Field: AdditionalOperations (OpenAPI 3.2)
+        /// </summary>
+        public const string AdditionalOperations = "additionalOperations";
+
         /// <summary>
         /// Field: ExtensionFieldNamePrefix
         /// </summary>

src/Microsoft.OpenApi/Models/OpenApiPathItem.cs

@@ -27,6 +27,12 @@ public class OpenApiPathItem : IOpenApiExtensible, IOpenApiPathItem
         /// <inheritdoc/>
         public IList<IOpenApiParameter>? Parameters { get; set; }
 
+        /// <inheritdoc/>
+        public OpenApiOperation? Query { get; set; }
+
+        /// <inheritdoc/>
+        public IDictionary<string, OpenApiOperation>? AdditionalOperations { get; set; }
+
         /// <inheritdoc/>
         public IDictionary<string, IOpenApiExtension>? Extensions { get; set; }
 
@@ -57,6 +63,8 @@ internal OpenApiPathItem(IOpenApiPathItem pathItem)
             Operations = pathItem.Operations != null ? new Dictionary<HttpMethod, OpenApiOperation>(pathItem.Operations) : null;
             Servers = pathItem.Servers != null ? [.. pathItem.Servers] : null;
             Parameters = pathItem.Parameters != null ? [.. pathItem.Parameters] : null;
+            Query = pathItem.Query != null ? new OpenApiOperation(pathItem.Query) : null;
+            AdditionalOperations = pathItem.AdditionalOperations != null ? new Dictionary<string, OpenApiOperation>(pathItem.AdditionalOperations) : null;
             Extensions = pathItem.Extensions != null ? new Dictionary<string, IOpenApiExtension>(pathItem.Extensions) : null;
         }
 
@@ -73,15 +81,15 @@ public virtual void SerializeAsV32(IOpenApiWriter writer)
         /// </summary>
         public virtual void SerializeAsV31(IOpenApiWriter writer)
         {
-            SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_1, (writer, element) => element.SerializeAsV31(writer));
+            SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_1, (writer, element) => element.SerializeAsV31(writer), downgradeFrom32: true);
         }
 
         /// <summary>
         /// Serialize <see cref="OpenApiPathItem"/> to Open Api v3.0
         /// </summary>
         public virtual void SerializeAsV3(IOpenApiWriter writer)
         {
-            SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (writer, element) => element.SerializeAsV3(writer));
+            SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (writer, element) => element.SerializeAsV3(writer), downgradeFrom32: true);
         }
 
         /// <summary>
@@ -120,14 +128,17 @@ public virtual void SerializeAsV2(IOpenApiWriter writer)
                 OpenApiConstants.ExtensionFieldNamePrefix + OpenApiConstants.Description,
                 Description);
 
+            // Write Query and AdditionalOperations as extensions when downgrading to v2
+            WriteV32FieldsAsExtensions(writer);
+
             // specification extensions
             writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
 
             writer.WriteEndObject();
         }
 
         internal virtual void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version,
-            Action<IOpenApiWriter, IOpenApiSerializable> callback)
+            Action<IOpenApiWriter, IOpenApiSerializable> callback, bool downgradeFrom32 = false)
         {
             Utils.CheckArgumentNull(writer);
 
@@ -151,6 +162,21 @@ internal virtual void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersio
                 }
             }
 
+            // OpenAPI 3.2 specific fields
+            if (version == OpenApiSpecVersion.OpenApi3_2)
+            {
+                // query operation
+                writer.WriteOptionalObject(OpenApiConstants.Query, Query, callback);
+
+                // additional operations
+                writer.WriteOptionalMap(OpenApiConstants.AdditionalOperations, AdditionalOperations, callback);
+            }
+            else if (downgradeFrom32)
+            {
+                // When downgrading from 3.2 to 3.1/3.0, serialize as extensions
+                WriteV32FieldsAsExtensions(writer);
+            }
+
             // servers
             writer.WriteOptionalCollection(OpenApiConstants.Servers, Servers, callback);
 
@@ -163,6 +189,29 @@ internal virtual void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersio
             writer.WriteEndObject();
         }
 
+        /// <summary>
+        /// Writes OpenAPI 3.2 specific fields as extensions when downgrading to older versions
+        /// </summary>
+        private void WriteV32FieldsAsExtensions(IOpenApiWriter writer)
+        {
+            if (Query != null)
+            {
+                writer.WritePropertyName(OpenApiConstants.ExtensionFieldNamePrefix + "oas-" + OpenApiConstants.Query);
+                Query.SerializeAsV31(writer);
+            }
+
+            if (AdditionalOperations != null && AdditionalOperations.Count > 0)
+            {
+                writer.WritePropertyName(OpenApiConstants.ExtensionFieldNamePrefix + "oas-" + OpenApiConstants.AdditionalOperations);
+                writer.WriteStartObject();
+                foreach (var kvp in AdditionalOperations)
+                {
+                    writer.WriteOptionalObject(kvp.Key, kvp.Value, (w, o) => o.SerializeAsV31(w));
+                }
+                writer.WriteEndObject();
+            }
+        }
+
         /// <inheritdoc/>
         public IOpenApiPathItem CreateShallowCopy()
         {

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

@@ -58,6 +58,12 @@ public string? Description
         /// <inheritdoc/>
         public IList<IOpenApiParameter>? Parameters { get => Target?.Parameters; }
 
+        /// <inheritdoc/>
+        public OpenApiOperation? Query { get => Target?.Query; }
+
+        /// <inheritdoc/>
+        public IDictionary<string, OpenApiOperation>? AdditionalOperations { get => Target?.AdditionalOperations; }
+
         /// <inheritdoc/>
         public IDictionary<string, IOpenApiExtension>? Extensions { get => Target?.Extensions; }
 

src/Microsoft.OpenApi/Reader/V3/OpenApiPathItemDeserializer.cs

@@ -41,6 +41,8 @@ internal static partial class OpenApiV3Deserializer
         private static readonly PatternFieldMap<OpenApiPathItem> _pathItemPatternFields =
             new()
             {
+                {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix + "oas-query", StringComparison.OrdinalIgnoreCase), (o, p, n, t) => o.Query = LoadOperation(n, t)},
+                {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix + "oas-additionalOperations", StringComparison.OrdinalIgnoreCase), (o, p, n, t) => o.AdditionalOperations = n.CreateMap(LoadOperation, t)},
                 {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix, StringComparison.OrdinalIgnoreCase), (o, p, n, _) => o.AddExtension(p, LoadExtension(p,n))}
             };
 

src/Microsoft.OpenApi/Reader/V31/OpenApiPathItemDeserializer.cs

@@ -43,6 +43,8 @@ internal static partial class OpenApiV31Deserializer
         private static readonly PatternFieldMap<OpenApiPathItem> _pathItemPatternFields =
             new()
             {
+                {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix + "oas-query", StringComparison.OrdinalIgnoreCase), (o, p, n, t) => o.Query = LoadOperation(n, t)},
+                {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix + "oas-additionalOperations", StringComparison.OrdinalIgnoreCase), (o, p, n, t) => o.AdditionalOperations = n.CreateMap(LoadOperation, t)},
                 {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix, StringComparison.OrdinalIgnoreCase), (o, p, n, _) => o.AddExtension(p, LoadExtension(p,n))}
             };
 

src/Microsoft.OpenApi/Reader/V32/OpenApiPathItemDeserializer.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Net.Http;
 
 namespace Microsoft.OpenApi.Reader.V32
@@ -36,8 +36,10 @@ internal static partial class OpenApiV32Deserializer
             {"patch", (o, n, t) => o.AddOperation(new HttpMethod("PATCH"), LoadOperation(n, t))},
 #endif
             {"trace", (o, n, t) => o.AddOperation(HttpMethod.Trace, LoadOperation(n, t))},
+            {"query", (o, n, t) => o.Query = LoadOperation(n, t)},
             {"servers", (o, n, t) => o.Servers = n.CreateList(LoadServer, t)},
-            {"parameters", (o, n, t) => o.Parameters = n.CreateList(LoadParameter, t)}
+            {"parameters", (o, n, t) => o.Parameters = n.CreateList(LoadParameter, t)},
+            {"additionalOperations", (o, n, t) => o.AdditionalOperations = n.CreateMap(LoadOperation, t)}
         };
 
         private static readonly PatternFieldMap<OpenApiPathItem> _pathItemPatternFields =