Add APIs for viewing generated OpenAPI file at runtime

[captainsafia]

Background and Motivation

See #54598 for full background and motivation.

As part of our effort to add built-in support for OpenAPI document generation in the framework, we are adding APIs to register OpenAPI-related services and endpoints in the target user app.

Proposed API

Note: All APIs are net new.

// Assembly: Microsoft.AspNetCore.OpenApi
namespace Microsoft.AspNetCore.Builder;

public static class IEndpointRouteBuilderExtensions
{
  public static IEndpointRouteBuilder MapOpenApi(this IEndpointRouteBuilder builder);
}

// Assembly: Microsoft.AspNetCore.OpenApi
namespace Microsoft.Extensions.DependencyInjection;

public static class IServiceCollectionExtensions
{
  public static IServiceCollection AddOpenApi(this IServiceCollection serviceCollection);
  public static IServiceCollection AddOpenApi(this IServiceCollection serviceCollection, Action<OpenApiOptions> configureOptions);
}

// Assembly: Microsoft.AspNetCore.OpenApi
namespace Microsoft.AspNetCore.OpenApi;

public class OpenApiOptions
{
  public string JsonFilePath { get; set; }
  public OpenApiSpecVersion OpenApiVersion { get; set; }
}

Usage Examples

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/", () => "Hello world!");

app.Run();

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi(options =>
{
  options.JsonFilePath = "/custom.openapi.json";
});

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/", () => "Hello world!");

app.Run();

Alternative Designs

N/A

Risks

N/A

[dotnet-policy-service]

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.

[halter73]

API Review:

• Do we like MapOpenApiJson to be more explicit this doesn't include stuff like Swagger UI?
  • Or MapOpenApiDocuments?
  • Let's stick with MapOpenApi for now, but reserve the right to change it MapOpenApiDocuments in a later preview when we add multi-document support.
• MapOpenApi should return an IEndpointConventionBuilder
  • It could return a derived type for OpenAPI-specific extension methods similar to MapHub, but we don't think we need it.
• OpenApiOptions.JsonFilePath shouldn't be called a "file path" since it's really a route
  • JsonRoute? DocumentRoute? JsonDocumentRoute?
    • DocumentRoute is less prescriptive. We might add something like yaml support later.
  • And make it a RoutePattern? Let's not make people call RoutePattern.Parse().
  • Or do we take it as the second parameter to MapOpenApi()? Yes.
• Where is OpenApiSpecVersion defined? Third party dependency on Microsoft.OpenApi.
  • We think this API is already so inextricably tied to Microsoft.OpenApi that we don't think we lose anything by exposing their types on OpenApiOptions. This puts us in a similar spot we are in with Microsoft.IdentityModel and our JwtBearer/OpenIdConnect/WsFed
• IEndpointRouteBuilderExtensions and IServiceCollectionExtensions should be renamed to OpenApiEndpointRouteBuilderExtensions and OpenApiServiceCollectionExtensions.
• We might like an API where you can also specify the version along with MapOpenApi to keep all the configuration in one place and potentially support multiple calls, but that is a more complicated API that might involve a custom IEndopintConventionBuilder
  • Or, if we add no other options before .NET 9, we should consider making OpenApiSpecVersion the last argument to MapOpenApi

API Approved!

// Assembly: Microsoft.AspNetCore.OpenApi
namespace Microsoft.AspNetCore.Builder;

public static class OpenApiEndpointRouteBuilderExtensions
{
    public static IEndpointConventionBuilder MapOpenApi(this IEndpointRouteBuilder builder, [StringSyntax("Route")] string pattern = "openapi.json");
}

namespace Microsoft.Extensions.DependencyInjection;

public static class OpenApiServiceCollectionExtensions
{
    public static IServiceCollection AddOpenApi(this IServiceCollection serviceCollection);
    public static IServiceCollection AddOpenApi(this IServiceCollection serviceCollection, Action<OpenApiOptions> configureOptions);
}

namespace Microsoft.AspNetCore.OpenApi;

public class OpenApiOptions
{
    public OpenApiSpecVersion OpenApiVersion { get; set; }
}

[mitchdenny]

Has anyone ever asked for the ability to split up their open API document into multiple different endpoints? Do we assume that there is only ever one OpenAPI document for the entire app?

[captainsafia]

Has anyone ever asked for the ability to split up their open API document into multiple different endpoints? Do we assume that there is only ever one OpenAPI document for the entire app?

Yes, there's often a need to do multiple documents for different versions of an API or different visibilities (public versus internal).

#54676 outlines how we intend to do this.

[captainsafia]

Closing as this is merged to main.