Introduce Microsoft.AspNetCore.OpenApi package

[DamianEdwards]

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.

[davidfowl]

cc @darrelmiller @bradygaster

[bradygaster]

i really like this idea.

[bradygaster]

Also DM's library can translate betwixt versions of OpenAPI (and output format - YAML/JSON). We could use that.

[darrelmiller]

Sign us up.

Thanks for contacting us.

We're moving this issue to the .NET 7 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.