Support resolving OpenApiPaths entries from document (#54847)

* Add support for generating OpenAPI info and paths

* Address feedback

* Fix sample and options injection

* Address more feedback

Author: captainsafia

src/Mvc/Mvc.ApiExplorer/src/Microsoft.AspNetCore.Mvc.ApiExplorer.csproj

@@ -20,5 +20,6 @@
 
   <ItemGroup>
     <InternalsVisibleTo Include="Microsoft.AspNetCore.Mvc.ApiExplorer.Test" />
+    <InternalsVisibleTo Include="Microsoft.AspNetCore.OpenApi.Tests" />
   </ItemGroup>
 </Project>

src/OpenApi/sample/Program.cs

@@ -1,9 +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 Microsoft.AspNetCore.Builder;
-using Microsoft.AspNetCore.Mvc;
-
 var builder = WebApplication.CreateBuilder(args);
 
 builder.Services.AddOpenApi("v1");
@@ -18,14 +15,16 @@
 }
 
 var v1 = app.MapGroup("v1")
-    .WithMetadata(new ApiExplorerSettingsAttribute { GroupName = "v1" });
+    .WithGroupName("v1");
 
 var v2 = app.MapGroup("v2")
-    .WithMetadata(new ApiExplorerSettingsAttribute { GroupName = "v2" });
+    .WithGroupName("v2");
 
 v1.MapPost("/todos", (Todo todo) => Results.Created($"/todos/{todo.Id}", todo));
 v1.MapGet("/todos/{id}", (int id) => new TodoWithDueDate(1, "Test todo", false, DateTime.Now.AddDays(1), DateTime.Now));
 
+v2.MapPost("/users", () => Results.Created("/users/1", new { Id = 1, Name = "Test user" }));
+
 app.Run();
 
 public record Todo(int Id, string Title, bool Completed, DateTime CreatedAt);

src/OpenApi/src/Extensions/ApiDescriptionExtensions.cs

@@ -0,0 +1,73 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics;
+using System.Text;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.AspNetCore.Routing.Patterns;
+using Microsoft.OpenApi.Models;
+
+internal static class ApiDescriptionExtensions
+{
+    /// <summary>
+    /// Maps the HTTP method of the ApiDescription to the OpenAPI <see cref="OperationType"/> .
+    /// </summary>
+    /// <param name="apiDescription">The ApiDescription to resolve an operation type from.</param>
+    /// <returns>The <see cref="OperationType"/> associated with the given <paramref name="apiDescription"/>.</returns>
+    public static OperationType GetOperationType(this ApiDescription apiDescription) =>
+        apiDescription.HttpMethod?.ToUpperInvariant() switch
+        {
+            "GET" => OperationType.Get,
+            "POST" => OperationType.Post,
+            "PUT" => OperationType.Put,
+            "DELETE" => OperationType.Delete,
+            "PATCH" => OperationType.Patch,
+            "HEAD" => OperationType.Head,
+            "OPTIONS" => OperationType.Options,
+            "TRACE" => OperationType.Trace,
+            _ => throw new InvalidOperationException($"Unsupported HTTP method: {apiDescription.HttpMethod}"),
+        };
+
+    /// <summary>
+    /// Maps the relative path included in the ApiDescription to the path
+    /// that should be included in the OpenApiDocument. This typically
+    /// consists of removing any constraints from route parameter parts
+    /// and retaining only the literals.
+    /// </summary>
+    /// <param name="apiDescription">The ApiDescription to resolve an item path from.</param>
+    /// <returns>The resolved item path for the given <paramref name="apiDescription"/>.</returns>
+    public static string MapRelativePathToItemPath(this ApiDescription apiDescription)
+    {
+        Debug.Assert(apiDescription.RelativePath != null, "Relative path cannot be null.");
+        // "" -> "/"
+        if (string.IsNullOrEmpty(apiDescription.RelativePath))
+        {
+            return "/";
+        }
+        var strippedRoute = new StringBuilder();
+        var routePattern = RoutePatternFactory.Parse(apiDescription.RelativePath);
+        for (var i = 0; i < routePattern.PathSegments.Count; i++)
+        {
+            strippedRoute.Append('/');
+            var segment = routePattern.PathSegments[i];
+            foreach (var part in segment.Parts)
+            {
+                if (part is RoutePatternLiteralPart literalPart)
+                {
+                    strippedRoute.Append(literalPart.Content);
+                }
+                else if (part is RoutePatternParameterPart parameterPart)
+                {
+                    strippedRoute.Append('{');
+                    strippedRoute.Append(parameterPart.Name);
+                    strippedRoute.Append('}');
+                }
+                else if (part is RoutePatternSeparatorPart separatorPart)
+                {
+                    strippedRoute.Append(separatorPart.Content);
+                }
+            }
+        }
+        return strippedRoute.ToString();
+    }
+}

src/OpenApi/src/Services/OpenApiDocumentService.cs

@@ -1,23 +1,75 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Diagnostics;
+using System.Linq;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Options;
 using Microsoft.OpenApi.Models;
 
 namespace Microsoft.AspNetCore.OpenApi;
 
-internal sealed class OpenApiDocumentService(IHostEnvironment hostEnvironment)
+internal sealed class OpenApiDocumentService(
+    [ServiceKey] string documentName,
+    IApiDescriptionGroupCollectionProvider apiDescriptionGroupCollectionProvider,
+    IHostEnvironment hostEnvironment,
+    IOptionsMonitor<OpenApiOptions> optionsMonitor)
 {
+    private readonly OpenApiOptions _options = optionsMonitor.Get(documentName);
+
     public Task<OpenApiDocument> GetOpenApiDocumentAsync()
     {
         var document = new OpenApiDocument
         {
-            Info = new OpenApiInfo
-            {
-                Title = hostEnvironment.ApplicationName,
-                Version = OpenApiConstants.DefaultOpenApiVersion
-            }
+            Info = GetOpenApiInfo(),
+            Paths = GetOpenApiPaths()
         };
         return Task.FromResult(document);
     }
+
+    // Note: Internal for testing.
+    internal OpenApiInfo GetOpenApiInfo()
+    {
+        return new OpenApiInfo
+        {
+            Title = $"{hostEnvironment.ApplicationName} | {documentName}",
+            Version = OpenApiConstants.DefaultOpenApiVersion
+        };
+    }
+
+    /// <summary>
+    /// Gets the OpenApiPaths for the document based on the ApiDescriptions.
+    /// </summary>
+    /// <remarks>
+    /// At this point in the construction of the OpenAPI document, we run
+    /// each API description through the `ShouldInclude` delegate defined in
+    /// the object to support filtering each
+    /// description instance into its appropriate document.
+    /// </remarks>
+    private OpenApiPaths GetOpenApiPaths()
+    {
+        var descriptionsByPath = apiDescriptionGroupCollectionProvider.ApiDescriptionGroups.Items
+            .SelectMany(group => group.Items)
+            .Where(_options.ShouldInclude)
+            .GroupBy(apiDescription => apiDescription.MapRelativePathToItemPath());
+        var paths = new OpenApiPaths();
+        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 = GetOperations(descriptions) });
+        }
+        return paths;
+    }
+
+    private static Dictionary<OperationType, OpenApiOperation> GetOperations(IGrouping<string?, ApiDescription> descriptions)
+    {
+        var operations = new Dictionary<OperationType, OpenApiOperation>();
+        foreach (var description in descriptions)
+        {
+            operations[description.GetOperationType()] = new OpenApiOperation();
+        }
+        return operations;
+    }
 }

src/OpenApi/test/Extensions/ApiDescriptionExtensionsTests.cs

@@ -0,0 +1,74 @@
+// 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.Mvc.ApiExplorer;
+using Microsoft.OpenApi.Models;
+
+public class ApiDescriptionExtensionsTests
+{
+    [Theory]
+    [InlineData("api/todos", "/api/todos")]
+    [InlineData("api/todos/{id}", "/api/todos/{id}")]
+    [InlineData("api/todos/{id:int:min(10)}", "/api/todos/{id}")]
+    [InlineData("{a}/{b}/{c=19}", "/{a}/{b}/{c}")]
+    [InlineData("{a}/{b}/{c?}", "/{a}/{b}/{c}")]
+    [InlineData("{a:int}/{b}/{c:int}", "/{a}/{b}/{c}")]
+    [InlineData("", "/")]
+    [InlineData("api", "/api")]
+    [InlineData("{p1}/{p2}.{p3?}", "/{p1}/{p2}.{p3}")]
+    public void MapRelativePathToItemPath_ReturnsItemPathForApiDescription(string relativePath, string expectedItemPath)
+    {
+        // Arrange
+        var apiDescription = new ApiDescription
+        {
+            RelativePath = relativePath
+        };
+
+        // Act
+        var itemPath = apiDescription.MapRelativePathToItemPath();
+
+        // Assert
+        Assert.Equal(expectedItemPath, itemPath);
+    }
+
+    [Theory]
+    [InlineData("GET", OperationType.Get)]
+    [InlineData("POST", OperationType.Post)]
+    [InlineData("PUT", OperationType.Put)]
+    [InlineData("DELETE", OperationType.Delete)]
+    [InlineData("PATCH", OperationType.Patch)]
+    [InlineData("HEAD", OperationType.Head)]
+    [InlineData("OPTIONS", OperationType.Options)]
+    [InlineData("TRACE", OperationType.Trace)]
+    [InlineData("gEt", OperationType.Get)]
+    public void ToOperationType_ReturnsOperationTypeForApiDescription(string httpMethod, OperationType expectedOperationType)
+    {
+        // Arrange
+        var apiDescription = new ApiDescription
+        {
+            HttpMethod = httpMethod
+        };
+
+        // Act
+        var operationType = apiDescription.GetOperationType();
+
+        // Assert
+        Assert.Equal(expectedOperationType, operationType);
+    }
+
+    [Theory]
+    [InlineData("UNKNOWN")]
+    [InlineData("unknown")]
+    public void ToOperationType_ThrowsForUnknownHttpMethod(string methodName)
+    {
+        // Arrange
+        var apiDescription = new ApiDescription
+        {
+            HttpMethod = methodName
+        };
+
+        // Act & Assert
+        var exception = Assert.Throws<InvalidOperationException>(() => apiDescription.GetOperationType());
+        Assert.Equal($"Unsupported HTTP method: {methodName}", exception.Message);
+    }
+}