How to add Swagger to your .NET 9 app

.NET 9 is out, and with it, the inclusion of the Swashbuckle Swagger package has ended. What does this mean for you and your project? Let’s investigate together!

The end of en era

Even though removing Swashbuckle Swagger package inclusion might feel like a trouble and a big thing, you don’t lose its core functionality, which is the generation of API documentation. To replace Swagger, Microsoft has introduced the built-in Microsoft.AspNetCore.OpenApi package. This native integration reduces reliance on third-party tools and provides a streamlined experience for developers. The new package simplifies configuration, offers better integration with minimal APIs, and maintains compatibility with existing tools that utilise OpenAPI specifications, but it misses one thing – built-in UI.

Alternative tools like NSwag or Scalar can still be used for interactive API documentation and testing. These tools can consume the OpenAPI JSON generated by the new package, ensuring flexibility in the development workflow.

But that’s not all! If you don’t mind the “official” or “semi-official” reasons behind this package removal, which is: lack of active maintenance and the absence of an official release for .NET 8, you can still use SwaggerUI to represent your endpoints visually.

‼️ It’s essential to remember that after upgrading your pre-existing solution to .NET 9 the Swagger will still be working fine. Above all, the Swashbuckle Swagger package has already been installed!

Let’s see different alternatives.

OpenApi

If you don’t need any visualisation, the new package provided should be enough for you.

First, make sure to install Microsoft.AspNetCore.OpenApi package if it’s not yet included. Then, configure OpenAPI in the Program.cs file ⬇️ (include app.UseOpenApi();

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

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

app.MapGet("hello", () => "Hello, World!")
    .WithName("Hello");

app.Run();

Now, the OpenAPI document is available at /openapi/v1.json by default and will look like on the picture below.

OpenApi with Swagger UI

As stated before, you can still use Swashbuckle Swagger, either as a whole with the old setup or just the UI (we’ll now show the second option).

To start with, install the Swashbuckle.AspNetCore.SwaggerUI NuGet package if you don’t have it already. I recommend uninstalling Swashbuckle.AspNetCore if you want to use this combination so that you don’t leave any unused package behind in your code and keep it crystal clear what your intentions are. Add Swagger UI middleware in the Program.cs ⬇️.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Dummy API");
    }); // Adds Swagger UI for interactive API testing
}
app.UseHttpsRedirection();

app.MapGet("hello", () => "Hello, World!")
    .WithName("Hello");

app.Run();

From now on, you can find your swagger documentation at /swagger, which will give us the old good Swashbuckle swagger view:

OpenAPI with NSwag

Using NSwag instead of Swagger UI offers similar functionality but is a different tool.

To implement this approach, you should first install the NSwag.AspNetCore NuGet package. Then, Configure NSwag in Program.cs ⬇️.

var builder = WebApplication.CreateBuilder(args);

// Add OpenAPI services
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument(); // NSwag's equivalent of AddSwaggerGen

var app = builder.Build();

// Enable NSwag middleware
app.UseOpenApi(); // Generates OpenAPI JSON
app.UseSwaggerUi(); // Adds NSwag's Swagger UI

// Map a minimal API endpoint
app.MapGet("/hello", () => "Hello, NSwag!")
   .WithName("HelloEndpoint")
   .WithOpenApi();

app.Run();

The NSwag UI will be available at /swagger and look just like Swashbuckle Swagger if you don’t add any customisation.

You can read more about NSwag here.

NSwag vs. Swashbuckle

There are several key differences between Swashbackle and NSwag, that you might want to consider before meking a decision. Let me briefly talk about some of them.

First, it offers built-in support for client code generation (NSwag). With Swashbuckle, you have to rely on additional tools. Secondly, NSwag offers more customisation of UI. It supports features like adding custom operation filters or modifying the generated OpenAPI document on the fly. Lastly, I think we should mention support and maintenance. While Swashbuckle has been the standard for many years, it has seen slower updates recently. NSwag, on the other hand, is actively maintained and receives regular updates, making it a more future-proof choice.

Summary

If you’re starting a new .NET 9 project or adopting OpenAPI for the first time, NSwag is a strong candidate to consider. However, if you already have strong Swashbuckle Swagger skills (personally or at your company), or you maintain mature applications that use Swashbuckle Swagger, consider giving it a deep thought whether the refactoring is what you want to invest the time

Check out our previous posts about the Unicorns of Web development! Stay tuned for more content!