[OpenApi] Ignore unknown HTTP methods (dotnet#63034)

* [OpenApi] Ignore unknown HTTP methods

Exclude unsupported HTTP methods from the OpenAPI document, rather than throwing an exception.

Resolves dotnet#60914.

* [OpenApi] Support HTTP QUERY

Support generating OpenAPI documentation for HTTP QUERY endpoints.

Contributes to dotnet#61089.

Author: martincostello

src/OpenApi/sample/Controllers/TestController.cs

@@ -5,6 +5,7 @@
 using System.Diagnostics.CodeAnalysis;
 using Microsoft.AspNetCore.Http.HttpResults;
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Routing;
 
 [ApiController]
 [Route("[controller]")]
@@ -39,6 +40,24 @@ public Ok<CurrentWeather> GetCurrentWeather()
         return TypedResults.Ok(new CurrentWeather(1.0f));
     }
 
+    [Route("/nohttpmethod")]
+    public ActionResult<CurrentWeather> NoHttpMethod()
+        => Ok(new CurrentWeather(-100));
+
+    [HttpQuery]
+    [Route("/query")]
+    public ActionResult<CurrentWeather> HttpQueryMethod()
+        => Ok(new CurrentWeather(0));
+
+    [HttpFoo] // See https://github.com/dotnet/aspnetcore/issues/60914
+    [Route("/unsupported")]
+    public ActionResult<CurrentWeather> UnsupportedHttpMethod()
+        => Ok(new CurrentWeather(100));
+
+    public class HttpQuery() : HttpMethodAttribute(["QUERY"]);
+
+    public class HttpFoo() : HttpMethodAttribute(["FOO"]);
+
     public class RouteParamsContainer
     {
         [FromRoute]

src/OpenApi/src/Extensions/ApiDescriptionExtensions.cs

@@ -16,8 +16,8 @@ internal static class ApiDescriptionExtensions
     /// Maps the HTTP method of the ApiDescription to the HttpMethod.
     /// </summary>
     /// <param name="apiDescription">The ApiDescription to resolve an HttpMethod from.</param>
-    /// <returns>The <see cref="HttpMethod"/> associated with the given <paramref name="apiDescription"/>.</returns>
-    public static HttpMethod GetHttpMethod(this ApiDescription apiDescription) =>
+    /// <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
         {
             "GET" => HttpMethod.Get,
@@ -28,7 +28,8 @@ public static HttpMethod GetHttpMethod(this ApiDescription apiDescription) =>
             "HEAD" => HttpMethod.Head,
             "OPTIONS" => HttpMethod.Options,
             "TRACE" => HttpMethod.Trace,
-            _ => throw new InvalidOperationException($"Unsupported HTTP method: {apiDescription.HttpMethod}"),
+            "QUERY" => HttpMethod.Query,
+            _ => null,
         };
 
     /// <summary>

src/OpenApi/src/Services/OpenApiDocumentService.cs

@@ -250,8 +250,13 @@ private async Task<OpenApiPaths> GetOpenApiPathsAsync(
         foreach (var descriptions in descriptionsByPath)
         {
             Debug.Assert(descriptions.Key != null, "Relative path mapped to OpenApiPath key cannot be null.");
-            paths.Add(descriptions.Key, new OpenApiPathItem { Operations = await GetOperationsAsync(descriptions, document, scopedServiceProvider, operationTransformers, schemaTransformers, cancellationToken) });
+            var operations = await GetOperationsAsync(descriptions, document, scopedServiceProvider, operationTransformers, schemaTransformers, cancellationToken);
+            if (operations.Count > 0)
+            {
+                paths.Add(descriptions.Key, new OpenApiPathItem { Operations = operations });
+            }
         }
+
         return paths;
     }
 
@@ -280,7 +285,14 @@ private async Task<Dictionary<HttpMethod, OpenApiOperation>> GetOperationsAsync(
             };
 
             _operationTransformerContextCache.TryAdd(description.ActionDescriptor.Id, operationContext);
-            operations[description.GetHttpMethod()] = operation;
+
+            if (description.GetHttpMethod() is not { } method)
+            {
+                // Skip unsupported HTTP methods
+                continue;
+            }
+
+            operations[method] = operation;
 
             // Use index-based for loop to avoid allocating an enumerator with a foreach.
             for (var i = 0; i < operationTransformers.Length; i++)

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

@@ -63,20 +63,4 @@ public void GetHttpMethod_ReturnsHttpMethodForApiDescription(string httpMethod,
         // Assert
         Assert.Equal(expectedHttpMethod, result);
     }
-
-    [Theory]
-    [InlineData("UNKNOWN")]
-    [InlineData("unknown")]
-    public void GetHttpMethod_ThrowsForUnknownHttpMethod(string methodName)
-    {
-        // Arrange
-        var apiDescription = new ApiDescription
-        {
-            HttpMethod = methodName
-        };
-
-        // Act & Assert
-        var exception = Assert.Throws<InvalidOperationException>(() => apiDescription.GetHttpMethod());
-        Assert.Equal($"Unsupported HTTP method: {methodName}", exception.Message);
-    }
 }

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

@@ -124,6 +124,35 @@
           }
         }
       }
+    },
+    "/query": {
+      "query": {
+        "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"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {

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

@@ -124,6 +124,35 @@
           }
         }
       }
+    },
+    "/query": {
+      "query": {
+        "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"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {

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

@@ -1233,6 +1233,35 @@
           }
         }
       }
+    },
+    "/query": {
+      "query": {
+        "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"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {