feat: adds support for additional operations emission in OpenAPI 3.2.0

src/OpenApi/src/Extensions/ApiDescriptionExtensions.cs

@@ -17,10 +17,16 @@ internal static class ApiDescriptionExtensions
     /// </summary>
     /// <param name="apiDescription">The ApiDescription to resolve an HttpMethod from.</param>
     /// <returns>The <see cref="HttpMethod"/> associated with the given <paramref name="apiDescription"/>, if known.</returns>
-    public static HttpMethod? GetHttpMethod(this ApiDescription apiDescription) =>
-        apiDescription.HttpMethod?.ToUpperInvariant() switch
+    public static HttpMethod? GetHttpMethod(this ApiDescription apiDescription)
+    {
+        var httpMethod = apiDescription.HttpMethod?.ToUpperInvariant();
+        if (string.IsNullOrWhiteSpace(httpMethod))
+        {
+            return null;
+        }
+
+        return httpMethod switch
         {
-            // Only add methods documented in the OpenAPI spec: https://spec.openapis.org/oas/v3.2.0.html#path-item-object
             "GET" => HttpMethod.Get,
             "POST" => HttpMethod.Post,
             "PUT" => HttpMethod.Put,
@@ -30,8 +36,9 @@ internal static class ApiDescriptionExtensions
             "OPTIONS" => HttpMethod.Options,
             "TRACE" => HttpMethod.Trace,
             "QUERY" => HttpMethod.Query,
-            _ => null,
+            _ => new HttpMethod(httpMethod),
         };
+    }
 
     /// <summary>
     /// Maps the relative path included in the ApiDescription to the path

src/OpenApi/src/Services/OpenApiConstants.cs

@@ -1,8 +1,6 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-using System.Net.Http;
-
 namespace Microsoft.AspNetCore.OpenApi;
 
 internal static class OpenApiConstants
@@ -19,21 +17,6 @@ internal static class OpenApiConstants
     internal const string RefPrefix = "#";
     internal const string NullableProperty = "x-is-nullable-property";
     internal const string DefaultOpenApiResponseKey = "default";
-    // Since there's a finite set of HTTP methods that can be included in a given
-    // OpenApiPaths, we can pre-allocate an array of these methods and use a direct
-    // lookup on the OpenApiPaths dictionary to avoid allocating an enumerator
-    // over the KeyValuePairs in OpenApiPaths.
-    internal static readonly HttpMethod[] HttpMethods = [
-        HttpMethod.Get,
-        HttpMethod.Post,
-        HttpMethod.Put,
-        HttpMethod.Delete,
-        HttpMethod.Options,
-        HttpMethod.Head,
-        HttpMethod.Patch,
-        HttpMethod.Trace,
-        HttpMethod.Query
-    ];
     // Represents primitive types that should never be represented as
     // a schema reference and always inlined.
     internal static readonly List<Type> PrimitiveTypes =

src/OpenApi/src/Services/OpenApiDocumentService.cs

@@ -163,14 +163,13 @@ internal async Task ForEachOperationAsync(
     {
         foreach (var pathItem in document.Paths.Values)
         {
-            for (var i = 0; i < OpenApiConstants.HttpMethods.Length; i++)
+            if (pathItem.Operations is null)
             {
-                var httpMethod = OpenApiConstants.HttpMethods[i];
-                if (pathItem.Operations is null || !pathItem.Operations.TryGetValue(httpMethod, out var operation))
-                {
-                    continue;
-                }
+                continue;
+            }
 
+            foreach (var operation in pathItem.Operations.Values)
+            {
                 if (operation.Metadata is { } annotations &&
                     annotations.TryGetValue(OpenApiConstants.DescriptionId, out var descriptionId) &&
                     descriptionId is string descriptionIdString &&
@@ -294,7 +293,7 @@ private async Task<Dictionary<HttpMethod, OpenApiOperation>> GetOperationsAsync(
 
             if (description.GetHttpMethod() is not { } method)
             {
-                // Skip unsupported HTTP methods
+                // Skip descriptions with no HTTP method.
                 continue;
             }
 

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Extensions/ApiDescriptionExtensionsTests.cs

@@ -91,18 +91,31 @@ public void GetHttpMethod_ReturnsHttpMethodForApiDescription(string httpMethod,
     }
 
     [Fact]
-    public void GetHttpMethod_ReturnsNullForUnsupportedMethod()
+    public void GetHttpMethod_ReturnsCustomHttpMethodForUnsupportedMethod()
     {
-        // Arrange - Test that unsupported HTTP methods return null
         var apiDescription = new ApiDescription
         {
-            HttpMethod = "UNSUPPORTED"
+            HttpMethod = "foo"
+        };
+
+        var result = apiDescription.GetHttpMethod();
+
+        Assert.Equal(new HttpMethod("FOO"), result);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    public void GetHttpMethod_ReturnsNullWhenApiDescriptionHasNoHttpMethod(string httpMethod)
+    {
+        var apiDescription = new ApiDescription
+        {
+            HttpMethod = httpMethod
         };
 
-        // Act
         var result = apiDescription.GetHttpMethod();
 
-        // Assert
         Assert.Null(result);
     }
 }

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_0/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=controllers.verified.txt

@@ -156,6 +156,37 @@
         }
       }
     },
+    "/unsupported": {
+      "x-oai-additionalOperations": {
+        "FOO": {
+          "tags": [
+            "Test"
+          ],
+          "responses": {
+            "200": {
+              "description": "OK",
+              "content": {
+                "text/plain": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                },
+                "application/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                },
+                "text/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/query-with-body": {
       "x-oai-additionalOperations": {
         "QUERY": {

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_1/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=controllers.verified.txt

@@ -156,6 +156,37 @@
         }
       }
     },
+    "/unsupported": {
+      "x-oai-additionalOperations": {
+        "FOO": {
+          "tags": [
+            "Test"
+          ],
+          "responses": {
+            "200": {
+              "description": "OK",
+              "content": {
+                "text/plain": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                },
+                "application/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                },
+                "text/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/query-with-body": {
       "x-oai-additionalOperations": {
         "QUERY": {

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_2/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=controllers.verified.txt

@@ -154,6 +154,37 @@
         }
       }
     },
+    "/unsupported": {
+      "additionalOperations": {
+        "FOO": {
+          "tags": [
+            "Test"
+          ],
+          "responses": {
+            "200": {
+              "description": "OK",
+              "content": {
+                "text/plain": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                },
+                "application/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                },
+                "text/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/query-with-body": {
       "query": {
         "tags": [

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant.verified.txt

@@ -1654,6 +1654,37 @@
         }
       }
     },
+    "/unsupported": {
+      "x-oai-additionalOperations": {
+        "FOO": {
+          "tags": [
+            "Test"
+          ],
+          "responses": {
+            "200": {
+              "description": "OK",
+              "content": {
+                "text/plain": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                },
+                "application/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                },
+                "text/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CurrentWeather"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/query-with-body": {
       "x-oai-additionalOperations": {
         "QUERY": {

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Services/OpenApiDocumentService/OpenApiDocumentServiceTests.QueryMethod.cs

@@ -5,6 +5,8 @@
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Routing;
+using Microsoft.Extensions.DependencyInjection;
 
 public partial class OpenApiDocumentServiceTests : OpenApiDocumentServiceTestBase
 {
@@ -71,7 +73,46 @@ await VerifyOpenApiDocument(builder, document =>
         });
     }
 
+    [Fact]
+    public async Task CustomMethod_AppearsInDocumentForMvcAction()
+    {
+        var action = CreateActionDescriptor(nameof(ActionWithCustomMethod));
+
+        await VerifyOpenApiDocument(action, document =>
+        {
+            var path = document.Paths["/api/custom"];
+            Assert.True(path.Operations.ContainsKey(new HttpMethod("FOO")));
+            Assert.DoesNotContain(HttpMethod.Post, path.Operations.Keys);
+        });
+    }
+
+    [Fact]
+    public async Task CustomMethod_IsVisitedByForEachOperationAsync()
+    {
+        var builder = CreateBuilder();
+        var action = CreateActionDescriptor(nameof(ActionWithCustomMethod));
+        var documentService = CreateDocumentService(builder, action);
+        var scopedService = builder.ServiceProvider.CreateScope();
+        var document = await documentService.GetOpenApiDocumentAsync(scopedService.ServiceProvider);
+
+        await documentService.ForEachOperationAsync(document, (operation, context, cancellationToken) =>
+        {
+            operation.Description = context.Description.HttpMethod;
+            return Task.CompletedTask;
+        }, CancellationToken.None);
+
+        var operation = document.Paths["/api/custom"].Operations[new HttpMethod("FOO")];
+        Assert.Equal("FOO", operation.Description);
+    }
+
     #nullable enable
     private record TodoItem(int Id, string Title, bool Completed);
 #nullable restore
+
+    [Route("/api/custom")]
+    [HttpFoo]
+    private ActionResult<TodoItem> ActionWithCustomMethod()
+        => new OkObjectResult(new TodoItem(100, "Title", true));
+
+    private sealed class HttpFooAttribute() : HttpMethodAttribute(["FOO"]);
 }