Add support for generating OpenAPI parameters

src/OpenApi/src/Extensions/ApiDescriptionExtensions.cs

@@ -4,6 +4,7 @@
 using System.Diagnostics;
 using System.Text;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.ModelBinding;
 using Microsoft.AspNetCore.Routing.Patterns;
 using Microsoft.OpenApi.Models;
 
@@ -70,4 +71,14 @@ public static string MapRelativePathToItemPath(this ApiDescription apiDescriptio
         }
         return strippedRoute.ToString();
     }
+
+    /// <summary>
+    /// Determines if the given <see cref="ApiParameterDescription" /> is a request body parameter.
+    /// </summary>
+    /// <param name="apiParameterDescription">The <see cref="ApiParameterDescription"/> to check. </param>
+    /// <returns>Returns <langword ref="true"/> if the given parameter comes from the request body, <langword ref="false"/> otherwise.</returns>
+    public static bool IsRequestBodyParameter(this ApiParameterDescription apiParameterDescription) =>
+        apiParameterDescription.Source == BindingSource.Body ||
+        apiParameterDescription.Source == BindingSource.FormFile ||
+        apiParameterDescription.Source == BindingSource.Form;
 }

src/OpenApi/src/Services/OpenApiDocumentService.cs

@@ -7,6 +7,7 @@
 using System.Linq;
 using Microsoft.AspNetCore.Http.Metadata;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.ModelBinding;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Options;
@@ -132,6 +133,7 @@ private static OpenApiOperation GetOperation(ApiDescription description, HashSet
         {
             Summary = GetSummary(description),
             Description = GetDescription(description),
+            Parameters = GetParameters(description),
             Tags = tags,
         };
         return operation;
@@ -154,4 +156,36 @@ private static OpenApiOperation GetOperation(ApiDescription description, HashSet
         // allows us to group endpoints by the "resource" concept (e.g. users, todos, etc.)
         return [new OpenApiTag { Name = description.ActionDescriptor.RouteValues["controller"] }];
     }
+
+    private static List<OpenApiParameter>? GetParameters(ApiDescription description)
+    {
+        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())
+            {
+                continue;
+            }
+
+            var openApiParameter = new OpenApiParameter
+            {
+                Name = parameter.Name,
+                In = parameter.Source.Id switch
+                {
+                    "Query" => ParameterLocation.Query,
+                    "Header" => ParameterLocation.Header,
+                    "Path" => ParameterLocation.Path,
+                    _ => throw new InvalidOperationException($"Unsupported parameter source: {parameter.Source.Id}")
+                },
+                // Per the OpenAPI specification, parameters that are sourced from the path
+                // are always required, regardless of the requiredness status of the parameter.
+                Required = parameter.Source == BindingSource.Path || parameter.IsRequired,
+            };
+            parameters ??= [];
+            parameters.Add(openApiParameter);
+        }
+        return parameters;
+    }
 }

src/OpenApi/test/Services/OpenApiDocumentServiceTests.Parameters.cs

@@ -0,0 +1,138 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.OpenApi.Models;
+
+public partial class OpenApiDocumentServiceTests : OpenApiDocumentServiceTestBase
+{
+    [Fact]
+    public async Task GetOpenApiParameters_GeneratesParameterLocationCorrectly()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapGet("/api/todos/{id}", (int id) => { });
+        builder.MapGet("/api/todos", (int id) => { });
+        builder.MapGet("/api", ([FromHeader(Name = "X-Header")] string header) => { });
+
+        // Assert
+        await VerifyOpenApiDocument(builder, document =>
+        {
+            var pathParameter = Assert.Single(document.Paths["/api/todos/{id}"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("id", pathParameter.Name);
+            Assert.Equal(ParameterLocation.Path, pathParameter.In);
+
+            var queryParameter = Assert.Single(document.Paths["/api/todos"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("id", queryParameter.Name);
+            Assert.Equal(ParameterLocation.Query, queryParameter.In);
+
+            var headerParameter = Assert.Single(document.Paths["/api"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("X-Header", headerParameter.Name);
+            Assert.Equal(ParameterLocation.Header, headerParameter.In);
+        });
+    }
+
+#nullable enable
+    [Fact]
+    public async Task GetOpenApiParameters_RouteParametersAreAlwaysRequired()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapGet("/api/todos/{id}", (int id) => { });
+        builder.MapGet("/api/todos/{guid}", (Guid? guid) => { });
+        builder.MapGet("/api/todos/{isCompleted}", (bool isCompleted = false) => { });
+
+        // Assert
+        await VerifyOpenApiDocument(builder, document =>
+        {
+            var pathParameter = Assert.Single(document.Paths["/api/todos/{id}"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("id", pathParameter.Name);
+            Assert.True(pathParameter.Required);
+            var guidParameter = Assert.Single(document.Paths["/api/todos/{guid}"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("guid", guidParameter.Name);
+            Assert.True(guidParameter.Required);
+            var isCompletedParameter = Assert.Single(document.Paths["/api/todos/{isCompleted}"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("isCompleted", isCompletedParameter.Name);
+            Assert.True(isCompletedParameter.Required);
+        });
+    }
+
+    [Fact]
+    public async Task GetOpenApiParameters_SetsRequirednessForQueryParameters()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapGet("/api/todos", (int id) => { });
+        builder.MapGet("/api/users", (int? id) => { });
+        builder.MapGet("/api/projects", (int id = 1) => { });
+
+        // Assert
+        await VerifyOpenApiDocument(builder, document =>
+        {
+            var queryParameter = Assert.Single(document.Paths["/api/todos"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("id", queryParameter.Name);
+            Assert.True(queryParameter.Required);
+            var nullableQueryParameter = Assert.Single(document.Paths["/api/users"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("id", nullableQueryParameter.Name);
+            Assert.False(nullableQueryParameter.Required);
+            var defaultQueryParameter = Assert.Single(document.Paths["/api/projects"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("id", defaultQueryParameter.Name);
+            Assert.False(defaultQueryParameter.Required);
+        });
+    }
+
+    [Fact]
+    public async Task GetOpenApiParameters_SetsRequirednessForHeaderParameters()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapGet("/api/todos", ([FromHeader(Name = "X-Header")] string header) => { });
+        builder.MapGet("/api/users", ([FromHeader(Name = "X-Header")] Guid? header) => { });
+        builder.MapGet("/api/projects", ([FromHeader(Name = "X-Header")] string header = "0000-0000-0000-0000") => { });
+
+        // Assert
+        await VerifyOpenApiDocument(builder, document =>
+        {
+            var headerParameter = Assert.Single(document.Paths["/api/todos"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("X-Header", headerParameter.Name);
+            Assert.True(headerParameter.Required);
+            var nullableHeaderParameter = Assert.Single(document.Paths["/api/users"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("X-Header", nullableHeaderParameter.Name);
+            Assert.False(nullableHeaderParameter.Required);
+            var defaultHeaderParameter = Assert.Single(document.Paths["/api/projects"].Operations[OperationType.Get].Parameters);
+            Assert.Equal("X-Header", defaultHeaderParameter.Name);
+            Assert.False(defaultHeaderParameter.Required);
+        });
+    }
+#nullable restore
+
+    [Fact]
+    public async Task GetOpenApiRequestBody_SkipsRequestBodyParameters()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapPost("/api/users", (IFormFile formFile, IFormFileCollection formFiles) => { });
+        builder.MapPost("/api/todos", (Todo todo) => { });
+
+        // Assert
+        await VerifyOpenApiDocument(builder, document =>
+        {
+            var usersOperation = document.Paths["/api/users"].Operations[OperationType.Post];
+            Assert.Null(usersOperation.Parameters);
+            var todosOperation = document.Paths["/api/todos"].Operations[OperationType.Post];
+            Assert.Null(todosOperation.Parameters);
+        });
+    }
+}

src/OpenApi/test/SharedTypes.cs

@@ -0,0 +1,11 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+// This file contains shared types that are used across tests, sample apps,
+// and benchmark apps.
+
+public record Todo(int Id, string Title, bool Completed, DateTime CreatedAt);
+
+public record TodoWithDueDate(int Id, string Title, bool Completed, DateTime CreatedAt, DateTime DueDate) : Todo(Id, Title, Completed, CreatedAt);
+
+public record Error(int code, string Message);