Alternatives to Swagger in ASP.NET 9: A Guide for .NET Developers

With the release of ASP.NET 9, Microsoft has introduced several noteworthy changes to the default project templates. One significant change is the removal of Swagger (Swashbuckle) from the templates. Swagger has long been a popular tool for documenting and interactively testing APIs, so this decision has raised questions among many .NET developers.

However, there’s no need to worry – several alternatives are available to help you build and test APIs interactively. In this article, we’ll explore why Swagger was removed and provide a detailed overview of various options to restore similar functionality in your projects.

Why was Swagger removed?

The decision to remove Swagger from the templates was driven by two main reasons:

1. Promoting Microsoft’s Own Implementation

Microsoft aims to emphasize its OpenAPI implementation under the Microsoft.AspNetCore.OpenApi namespace. This strategy reduces reliance on external libraries like Swashbuckle and provides a more streamlined, integrated solution for developers.

2. Swashbuckle’s Maintenance Status

While Swashbuckle is still functional, its active development has slowed down in recent years. Microsoft’s decision helps ensure a modern and future-ready approach for OpenAPI support.

The Minimal OpenAPI Solution in ASP.NET 9

A new ASP.NET 9 project includes a minimal OpenAPI configuration by default:

builder.Services.AddOpenApi();
var app = builder.Build();

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

This setup generates an OpenAPI specification accessible at:

https://localhost:<port>/openapi/v1.json

However, it lacks the interactive user interface that many developers have come to rely on.

Alternatives to Swagger

1. Reinstall Swashbuckle

The simplest way to bring back Swagger-UI is to manually reinstall Swashbuckle via NuGet package:

<PackageReference Include="Swashbuckle.AspNetCore" Version="6.7.3" />

After installation, update your Program.cs with the following:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

2. NSwag

NSwag is another powerful alternative that offers Swagger-like functionality. Additionally, it provides advanced features such as automatically generating TypeScript types, which is particularly beneficial for modern web applications. To use it, first install the NuGet package:

dotnet add package NSwag.AspNetCore

After installation, update your Program.cs with the following:

builder.Services.AddOpenApiDocument();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseOpenApi();
    app.UseSwaggerUi3();
}

3. Scalar

Scalar is a relatively new tool offering a sleek user interface and an intuitive onboarding experience. It’s ideal for teams looking for a modern and user-friendly solution. Scalar combines an elegant UI with robust ASP.NET integration, providing a fresh alternative to the more established tools. To use it, first install the NuGet package:

dotnet add package Scalar.AspNetCore

After installation, update your Program.cs with the following:

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

Conclusion

The removal of Swagger from ASP.NET 9 templates might seem like a step backward at first glance, but it opens the door to exploring new tools and approaches. Developers who prefer the tried-and-true can still rely on Swashbuckle. For modern projects requiring TypeScript integration or enhanced UI features, NSwag and Scalar are excellent alternatives. Ultimately, the choice depends on your project’s needs and workflow preferences. Whatever tool you choose, ASP.NET 9 remains a flexible and powerful platform – designed with .NET developers in mind.

Have you tried these tools? Share your experiences and tips in the comments! 😉