Enhance Your .NET 9 Web API with Scalar UI & Swagger's Robustness

Do you want clean API documentation for your .NET 9 Web API, but hesitant to rely on newer, less mature OpenAPI generators? You don’t have to choose! You can leverage the robustness of Swagger (Swashbuckle.AspNetCore) for OpenAPI generation and the stunning visuals of Scalar UI.

This post shows you how, drawing from a complete example with extension methods for a streamlined setup.

Why Combine Swagger and Scalar UI?

While .NET 9 introduces options for generating OpenAPI documents, many developers still trust the maturity and stability of Swagger (via Swashbuckle.AspNetCore). Scalar UI, on the other hand, provides a more modern and interactive user interface compared to the standard Swagger UI.

Key Steps

1. Project Setup (Existing .NET 9 Web API)

This assumes you have a .NET 9 Web API project with Swashbuckle.AspNetCore already configured for swagger.json generation. If not, checkout the GitHub repository for the complete example.

2. Install Scalar.AspNetCore

Add the Scalar.AspNetCore NuGet package:

dotnet add package Scalar.AspNetCore

3. Configure with extension methods

using Microsoft.OpenApi.Models;
using Scalar.AspNetCore;

namespace YourNamespace;

public static class OpenApiConfigurationExtensions
{
    public static void AddOpenApiConfiguration(this IServiceCollection services)
    {
        services.AddOpenApi();
        services.AddEndpointsApiExplorer();

        services.AddSwaggerGen(options =>
        {
            options.SwaggerDoc("v1", new OpenApiInfo
            {
                Title = "v1 Penguins API",
                Version = "v1",
                Description = "An example ASP.NET Core Web API using Swagger with Scalar UI",
            });
        });
    }

    public static void AddScalarUiConfiguration(this WebApplication app)
    {
        if (!app.Environment.IsDevelopment()) return;

        app.UseSwagger(); // Existing Swagger

        app.MapOpenApi().CacheOutput();

        app.MapScalarApiReference(options =>
        {
            options
                .WithTitle("v1 Penguins API")
                .WithTheme(ScalarTheme.DeepSpace)
                .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient)
                .WithOpenApiRoutePattern("/swagger/v1/swagger.json"); // Point to the generated swagger.json

            options.Servers ??= new List<ScalarServer>();
            options.Servers.Add(new ScalarServer("http://localhost:5063")); //Adjust as needed
        });
    }
}

4. Call extension methods in Program.cs

using YourNameSpace;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddOpenApiConfiguration(); // Call this extension method

var app = builder.Build();

app.AddScalarUiConfiguration(); // Call this extension method

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

5. Accessing Scalar UI

Run your .NET 9 Web API and navigate to the Scalar UI at http://localhost:<port>/scalar/v1.

Benefits of this approach

Swagger’s Reliable Generation: You continue to use Swashbuckle.AspNetCore, ensuring that your OpenAPI specification is generated with a mature and widely tested library.
Scalar UI’s Enhanced Interface: Your API documentation gets a significant visual and interactive upgrade with Scalar UI.
Clean Configuration: Extension methods make the setup process cleaner and more organized

View a complete example with source code on Github