Microsoft Dropped Swashbuckle—Here’s Why You Might Still Need It in .NET 9

Microsoft decided to remove Swashbuckle as a dependency from the Web API template in .NET 9. In its place, they introduced the Microsoft.AspNetCore.OpenApi package, a modern solution for generating OpenAPI/Swagger documents at runtime. This package is fully compatible with Native AOT, ensuring better performance and support for precompiled applications.

However, Microsoft do not include a native equivalent to the Swagger UI, which can make developers seek alternatives or even consider reintroducing Swashbuckle to regain access to the user-friendly, interactive API documentation and testing interface that Swagger UI provides.

The Swashbuckle Problem

Swashbuckle is a widely used NuGet package that simplifies the generation of OpenAPI/Swagger documentation. It utilizes ApiExplorer to discover available endpoints and generate the OpenAPI document, which SwaggerUI then leverages to provide an interactive web interface for testing HTTP requests.

Since .NET 5, Swashbuckle has been included in the templates for creating default Web API projects. This integration allows developers to add Swagger support during the setup of a new project.

With the release of .NET 7, Native AOT (Ahead-of-Time) compilation was introduced, imposing restrictions on reflection APIs—a core component of how Swashbuckle generates OpenAPI/Swagger documentation. This change led to compatibility issues, including errors related to unprocessed XML comments and JSON serialization failures with complex types.

In March 2024, Microsoft announced its own Microsoft.AspNetCore.OpenApi package. The new package was designed to be compatible with Native AOT, a feature that would require a complete rewrite of Swashbuckle to achieve similar support.

Additionally, critics pointed out that the Swashbuckle project had not received updates for almost a year, leading to an accumulation of unresolved issues and unmerged pull requests.

In May 2024, the Swashbuckle maintainer, Richie, resumed activity and began clearing the backlog of open pull requests. To ensure the project’s continuity, he delegated responsibilities to new team members, granting them permission to merge pull requests and manage the project in his absence.

Why Swashbuckle Still Matters

• The Microsoft native OpenAPI package lacks a web interface, but it can be combined with SwaggerUI to provide one.
• Swashbuckle remains compatible with .NET 6, .NET 7, .NET 8, and .NET 9 for projects that do not rely on Native AOT. In contrast, Microsoft OpenApi is only available starting from .NET 9.
• In May 2024, the maintainer of Swashbuckle resumed activity and addressed the backlog of open pull requests.
• Microsoft OpenApi does not support Seamless XML Comments Integration o que torna a sua documentação menos ric

As Richie explained in a discussion on GitHub, Swashbuckle is not a competitor to Microsoft.AspNetCore.OpenApi.

The new Microsoft package represents the future of OpenAPI/Swagger document generation and includes support for Native AOT. However, it is not yet mature enough to handle all the scenarios that Swashbuckle currently supports.

When to use Swashbuckle over the Microsoft OpenApi package

If your project does not have Native AOT requirements, you can go with Swashbuckle.

Step-by-Step Reintroduction of Swashbuckle

1. Remove Microsoft.AspNetCore.OpenApi packages.

If you have references like Microsoft.AspNetCore.OpenApi, remove them before proceeding.

2. Install Swashbuckle Manually

From your .csproj directory, run:

This output confirms a successful installation with no known vulnerabilities, an essential reassurance since the package was removed from official templates.

3. Update the Program.cs

After builder.Build(), add:

Inside the development block insert:

With these steps, Swashbuckle and Swagger UI are now integrated into your .NET 9 project.