Introduce Microsoft.AspNetCore.OpenApi package

Consider introducing a new package Microsoft.AspNetCore.OpenApi that provides integration features for ASP.NET Core HTTP APIs and OpenAPI. This package takes a dependency on Microsoft.OpenApi and contains the logic that maps primitive ASP.NET Core endpoint details to representations in endpoint metadata using the object model provided by Microsoft.OpenApi, along with projecting these details into the legacy ApiExplorer API from MVC. Furthermore, it provides helper methods for easily adding user-specified OpenAPI relevant details directly to endpoint metadata.

This would essentially be a strategy shift so that instead of continuing to add more metadata types to the framework to allow more details about endpoint APIs to be declared and published in MVC’s ApiExplorer (e.g. #40084), we embrace the existing OpenAPI object model in Microsoft.OpenApi and allow all operation details to be specified in an endpoint’s metadata and projected into ApiExplorer so that existing libraries like Swashbuckle continue to work.

The package would do the following:

• Depend on Microsoft.OpenApi
• Contain the logic that maps the MethodInfo for a route handler delegate in the endpoint metadata, to the requisite Microsoft.OpenApi.Models.OpenApiOperation
• Provide extension methods to easily allow mutating a route handler delegate’s OpenApi metadata, e.g.

  app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
      .WithOpenApiDetails(operation =>
      {
          operation.OperationId = "GetAllTodos";
          operation.Description = "This API returns all the Todos.";
      });
  

• Preserves the Microsoft.OpenApi.Models.OpenApiOperation in the endpoint metadata
  • This requires a new extensibility point be added such that the package can mutate the metadata for endpoints built by the route endpoint builder
• Contain the IApiDescriptionProvider that projects a route handler’s details from its OpenAPI endpoint metadata into ApiExplorer
• Be referenced in the Web API project template
• Would not reference Swashbuckle.AspNetCore, rather a project would still need to reference the SwaggerUI/OpenAPI library it wishes to use and call the requisite configuration methods for it to be configured

We need to consider of course how we do this without breaking (too much) stuff. In .NET 6, Minimal API endpoints are added to the ApiExplorer if MVC is configured, or the AddEndpointsApiExplorer() services extension method is called.

[jchannon]

[darrelmiller]

Sign us up.