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.

[ghost]

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.

[dosper7]

I'm sold 🤑 really like this one.

[jchannon]

[captainsafia]

Proposed API

namespace Microsoft.AspNetCore.OpenApi;

public static class OpenApiRouteHandlerBuilderExtensions
{
  public static RouteHandlerBuilder WithApiDescription(
    this RouteHandlerBuilder builder,
    Action<OpenApiPathItem>? configureDescription = null) { }
}

public static class OpenApiServicesExtensions
{
  public static IServiceCollection AddOpenApiGenerator(this IServiceCollection services) {}
}

public class OpenApiGenerator
{
  public OpenApiGenerator(
        IHostEnvironment? environment,
        IServiceProviderIsService? serviceProviderIsService) { }
}

namespace Microsoft.AspNetCore.Mvc;

public class ProducesResponseTypeAttribute : Attribute, IApiResponseMetadataProvider
{
-  internal bool IsResponseTypeSetByDefault { get; }
+  public bool IsResponseTypeSetByDefault { get; }
}

Usage Examples

var builder = WebApplication.CreateBuilder();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiGenerator();

var app = builder.Build();

app.MapGet("/todo/{id}", (int id) => {})
.WithApiDescription(desc => {
  desc.Operations[OperationType.Get].Summary = "Get a Todo by ID";
  desc.Operations[OperationType.Get].Parameters[0].Summary = "The ID associated with the Todo";
  desc.Operations[OperationType.Get].Parameters[0].Required = true;
});

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[DamianEdwards]

Some alternatives for AddOpenApiGenerator:

• AddOpenApiEndpoints
• AddOpenApiEndpointMetadata
• AddOpenApi

[captainsafia]

Note: WithApiDescription should change naming and input parameter.

WithOpenApi();
WithOpenApi(Func<OpenApiOperation, OpenApiOperation> produceOperation);

Remove:

public static IServiceCollection AddOpenApiGenerator(this IServiceCollection services) {}

Make this type internal:

internal class OpenApiGenerator
{
  internal OpenApiGenerator(
        IHostEnvironment? environment,
        IServiceProviderIsService? serviceProviderIsService) { }
}

[halter73]

API Review Notes:

• New sample usage (pending copy constructor Add support for copy constructors to Microsoft.OpenApi.Models objects microsoft/OpenAPI.NET#832).

using Microsoft.AspNetCore.OpenApi;

// ...

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

• Are we worried about the extensibility of OpenApiOperation since we do not own the type? No. We can lean on the OpenApiOperation.Extensions dictionary if we really must.

Final approved API:

+ namespace Microsoft.AspNetCore.OpenApi;
+
+ public static class OpenApiRouteHandlerBuilderExtensions
+ {
+   public static RouteHandlerBuilder WithOpenApi(this RouteHandlerBuilder builder)
+   public static RouteHandlerBuilder WithOpenApi(this RouteHandlerBuilder builder, Func<OpenApiOperation, OpenApiOperation> configureOperation)
+ }

namespace Microsoft.AspNetCore.Builder;

public abstract class EndpointBuilder
{
+  public IServiceProvider? ServiceProvider { get; set; }
}