With .NET 9, ASP.NET Core has charted a bold new course: built-in OpenAPI generation is now native — no more Swashbuckle/Swagger by default. But while the auto-generated JSON spec is great, what about a developer-friendly documentation UI?

Enter Scalar — a sleek, lightweight, and powerful alternative to Swagger UI. Let’s explore how .NET 9 and Scalar together offer a modern, efficient, and maintainable API documentation experience.

🛠 What Changed in .NET 9?
#

Until .NET 9, the default WebAPI templates included Swagger UI (via Swashbuckle). But that’s no longer the case. The .NET team deprecated built-in Swagger integration:

  • Swashbuckle isn’t maintained: It hasn’t officially supported .NET 8 and is seen as outdated
  • Built-in OpenAPI support replaces it: You can generate your API spec out of the box using:
1
2
3

builder.Services.AddOpenApi(); 

app.MapOpenApi();

That gives you a valid openapi/v1.json, but no visual interface.

🔧 Why Scalar Beats Swagger UI
#

Scalar steps in exactly where Swagger UI left off, offering several clear advantages:

  1. Faster & lighter UI — Ideal for large APIs, especially compared to Swagger UI’s sluggishness
  2. Cleaner, modern interface — Built-in dark mode, nice visuals, better usability
  3. Interactive features — Live request testing, authentication support, code snippets, and search
  4. Simple setup + no lock-in — Just install Scalar.AspNetCore and call app.MapScalarApiReference()
  5. Auto-generated client code — Instantly get C#, Java, and more API clients

Summary:

  • Speed for large APIs
  • UX that feels modern
  • Features like code examples and auth built-in
  • Ease of configuration with no extra hassle

⚙ Setup: .NET 9 + Scalar in Minutes
#

Install NuGet:

1
2

dotnet add package Microsoft.AspNetCore.OpenApi 
dotnet add package Scalar.AspNetCore

Configure in **Program.cs**:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", 
    "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
    {
        var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                (
                    DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    Random.Shared.Next(-20, 55),
                    summaries[Random.Shared.Next(summaries.Length)]
                ))
            .ToArray();
        return forecast;
    })
    .WithName("GetWeatherForecast");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Browse to https://localhost:<port>/scalar/v1 and enjoy your new interactive API docs.

Sample Scalar UI
Sample Scalar UI

Want to customize auth, themes, or endpoints? Scalar supports it all via fluent options.

🧭 When to Use Scalar
#

  • You like Swagger generation but not the clunky UI
  • You need fast, responsive docs, especially for large APIs
  • You want built-in live testing, search, code samples, and authentication

And best of all? Scalar plays well with ASP.NET 9’s new OpenAPI setup — no extra overhead.

🔁 Still Need Swagger?
#

No problem! You can still install Swashbuckle.AspNetCore and use both. But consider this: maintaining Swagger may become a burden—because it’s no longer part of the core .NET workflow. Scalar sticks to the modern, built-in path.

🎉 Final Thoughts
#

.NET 9 simplifies API spec generation. With Scalar, you get a sleek, powerful UI that’s easy to configure, lightweight, and packed with features.

Together, this combo is a clear upgrade over the old Swagger approach — especially for teams serious about developer experience.

You can find the demo code on my GitHub Profile.