Add built-in support for Swagger UI

[joegoldman2]

Introduction

With #55182, support for generating OpenAPI specification files has been added. However, the related feature to visualize these files, like Swagger UI, hasn't been included (and not planned from what I understood). This proposal aims to suggest the add of Swagger UI support within the framework to make it easier to visualize OpenAPI definitions.

Motivation

Visualizing OpenAPI Specification files is important for a better development experience. Swagger UI, with its easy-to-use interface and interactive documentation, helps developers to explore APIs in a practical way and test them easily (especially during the development phase).
Also, starting with .NET 9, users will migrate to the built-in feature to generate OpenAPI specifications (especially because Swashbuckle.AspNetCore will be removed from the web API template). However, this new feature doesn't cover the full functionality offered by the previous approach for working with OpenAPI (Swashbuckle.AspNetCore or NSwag).

Why Swagger UI?

While alternatives like Redoc exist, Swagger UI stands out due to its widespread adoption, robust feature set, and developer-friendly interface.

API Proposal

// namespace to be defined.

public class SwaggerUIOptions
{
    /// <summary>
    /// Gets or sets a route prefix for accessing the Swagger UI page. Defaults to swagger.
    /// </summary>
    public string RoutePrefix { get; set; } = "swagger";

    /// <summary>
    /// Gets or sets the document title for the Swagger UI page. Defaults to Swagger UI.
    /// </summary>
    public string DocumentTitle { get; set; } = "Swagger UI";
}

namespace Microsoft.Extensions.DependencyInjection;

public static class SwaggerUIServiceCollectionExtensions
{
    public static IServiceCollection AddSwaggerUI(this IServiceCollection services);
    public static IServiceCollection AddSwaggerUI(this IServiceCollection services, Action<SwaggerUIOptions> configure);
    public static IServiceCollection AddSwaggerUI(this IServiceCollection services, IConfiguration configuration);
}

namespace Microsoft.AspNetCore.Builder;

public static class SwaggerUIEndpointRouteBuilderExtensions
{
    public static IEndpointConventionBuilder MapSwaggerUI(this IEndpointRouteBuilder endpoints);
    public static IEndpointConventionBuilder MapSwaggerUI(this IEndpointRouteBuilder endpoints, SwaggerUIOptions options);
}

Usage Examples

var builder = WebApplication.CreateBuilder();

builder.Services.AddSwaggerUI();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapSwaggerUI();
}

app.Run();

Risks

N/A

[martincostello]

Just as a FYI (I have no problems with ASP.NET Core shipping its own SwaggerUI component), but Swashbuckle.AspNetCore has rebooted development (see domaindrivendev/Swashbuckle.AspNetCore#2778).

We have work in-flight to add support for .NET 8 (domaindrivendev/Swashbuckle.AspNetCore#2799), will likely have support for .NET 9 later this year, and we're trying to get our SwaggerUI support working with native AoT (domaindrivendev/Swashbuckle.AspNetCore#2800).

With those changes, you'd be able to use Swashbuckle's SwaggerUI functionality with the new OpenAPI functionality (I think!) as long as it's configured to know where the OpenAPI document is to fetch it if it's not at the same URL as it would be if Swashbuckle were rendering it.

With it no longer being in the templates, you'd just need to explicitly pull in the package reference and configure the services/middleware.

[joegoldman2]

Ok, very good news and I didn't know that development had finally resumed. Perhaps in this case my proposal is no longer really necessary.
I imagine you plan to migrate to the new built-in feature (.NET 9+) for the generation of the OpenAPI spec itself?

[martincostello]

I imagine you plan to migrate to the new built-in feature (.NET 9+) for the generation of the OpenAPI spec itself?

Unlikely, as that's the majority of what Swashbuckle does already. It would be a bit like getting NLog to reimplement itself in terms of Microsoft.Extensions.Logging - you wouldn't do that, you'd just use one or the other (maybe not the best analogy, as NLog is compatible with M.E.Logging...).

If there's new capabilities in ASP.NET Core itself, System.Text.Json or new C# language features as part of .NET 9, we'll look to support them where it makes sense.

[joegoldman2]

Thank you for the reply. In this case I still think it's useful that ASP.NET Core ships its own SwaggerUI component. Let's see the opinion of the other contributors.

[KennethHoff]

I imagine there will be plenty of third party packages (.. or at least one, which is all we really need..) that gives you a Swagger UI (or Redoc, or whatever) based on the first-party Microsoft OpenAPI document support.

[captainsafia]

@joegoldman2 Thanks for filing this issue! We don't plan on adding built-in support for Swagger UI as part of the work that we are doing here. You can read more about the scope of the work in this issue.

The TL;DR is that we don't want to take a strong opinion on what dev-time UI developers use to interact with the OpenAPI document we generate. Swagger UI is an option, but there's a variety of other tools in the space (Redoc mentioned by @KennethHoff above, Postman, Thunderclient) that give you the ability to visualize the APIs in your app.

With those changes, you'd be able to use Swashbuckle's SwaggerUI functionality with the new OpenAPI functionality (I think!) as long as it's configured to know where the OpenAPI document is to fetch it if it's not at the same URL as it would be if Swashbuckle were rendering it.

Yep, you should be able to use Swashbuckle's Swagger UI endpoint (or NSwag's for that matter) and point it to the JSON file we generate to produce the desired experience.

[joegoldman2]

Thank you for your reply. I understand and that's fair. I'm going to close this proposal.