Exclude some headers from OpenAPI parameters (#57328)

Do not include the `Accept`, `Authorization` and `Content-Type` headers in OpenAPI operation parameters.

Resolves #57305.

Author: martincostello

src/OpenApi/src/Services/OpenApiDocumentService.cs

@@ -1,6 +1,7 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Collections.Frozen;
 using System.ComponentModel;
 using System.ComponentModel.DataAnnotations;
 using System.Diagnostics;
@@ -22,6 +23,7 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Options;
+using Microsoft.Net.Http.Headers;
 using Microsoft.OpenApi.Models;
 
 namespace Microsoft.AspNetCore.OpenApi;
@@ -47,6 +49,8 @@ internal sealed class OpenApiDocumentService(
     private readonly Dictionary<string, OpenApiOperationTransformerContext> _operationTransformerContextCache = new();
     private static readonly ApiResponseType _defaultApiResponseType = new() { StatusCode = StatusCodes.Status200OK };
 
+    private static readonly FrozenSet<string> _disallowedHeaderParameters = new[] { HeaderNames.Accept, HeaderNames.Authorization, HeaderNames.ContentType }.ToFrozenSet(StringComparer.OrdinalIgnoreCase);
+
     internal bool TryGetCachedOperationTransformerContext(string descriptionId, [NotNullWhen(true)] out OpenApiOperationTransformerContext? context)
         => _operationTransformerContextCache.TryGetValue(descriptionId, out context);
 
@@ -393,9 +397,7 @@ private async Task<OpenApiResponse> GetResponseAsync(
         List<OpenApiParameter>? parameters = null;
         foreach (var parameter in description.ParameterDescriptions)
         {
-            // Parameters that should be in the request body should not be
-            // populated in the parameters list.
-            if (parameter.IsRequestBodyParameter())
+            if (ShouldIgnoreParameter(parameter))
             {
                 continue;
             }
@@ -419,6 +421,24 @@ private async Task<OpenApiResponse> GetResponseAsync(
             parameters.Add(openApiParameter);
         }
         return parameters;
+
+        static bool ShouldIgnoreParameter(ApiParameterDescription parameter)
+        {
+            if (parameter.IsRequestBodyParameter())
+            {
+                // Parameters that should be in the request body should not be
+                // populated in the parameters list.
+                return true;
+            }
+            else if (parameter.Source == BindingSource.Header && _disallowedHeaderParameters.Contains(parameter.Name))
+            {
+                // OpenAPI 3.0 states certain headers are "not allowed" to be defined as parameters.
+                // See https://github.com/dotnet/aspnetcore/issues/57305 for more context.
+                return true;
+            }
+
+            return false;
+        }
     }
 
     private static bool IsRequired(ApiParameterDescription parameter)

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

@@ -164,4 +164,30 @@ await VerifyOpenApiDocument(builder, document =>
             Assert.Null(todosOperation.Parameters);
         });
     }
+
+    [Fact]
+    public async Task GetOpenApiParameters_SkipsDisallowedHeaders()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapGet("/api/accept", ([FromHeader(Name = "Accept")] string value) => { });
+        builder.MapGet("/api/accept-lower", ([FromHeader(Name = "accept")] string value) => { });
+        builder.MapGet("/api/authorization", ([FromHeader(Name = "Authorization")] string value) => { });
+        builder.MapGet("/api/authorization-lower", ([FromHeader(Name = "authorization")] string value) => { });
+        builder.MapGet("/api/content-type", ([FromHeader(Name = "Content-Type")] string value) => { });
+        builder.MapGet("/api/content-type-lower", ([FromHeader(Name = "content-type")] string value) => { });
+
+        // Assert
+        await VerifyOpenApiDocument(builder, document =>
+        {
+            Assert.Null(document.Paths["/api/accept"].Operations[OperationType.Get].Parameters);
+            Assert.Null(document.Paths["/api/accept-lower"].Operations[OperationType.Get].Parameters);
+            Assert.Null(document.Paths["/api/authorization"].Operations[OperationType.Get].Parameters);
+            Assert.Null(document.Paths["/api/authorization-lower"].Operations[OperationType.Get].Parameters);
+            Assert.Null(document.Paths["/api/content-type"].Operations[OperationType.Get].Parameters);
+            Assert.Null(document.Paths["/api/content-type-lower"].Operations[OperationType.Get].Parameters);
+        });
+    }
 }