Microsoft has decided to remove the built-in Swagger support (Swashbuckle) from .NET 9.
Why is Swagger (Swashbuckle) Being Removed?
The ASP.NET Core team has decided to remove the built-in Swagger support (Swashbuckle) from .NET 9 for several reasons:
- Maintenance Issues: The Swashbuckle project is no longer actively maintained by its community owner. Issues aren't being addressed or resolved, and there wasn't an official release for .NET 8.
- Evolution of ASP.NET Core: Since the introduction of Swagger support in .NET 5, ASP.NET Core has evolved significantly. It now has built-in support for the metadata necessary to describe a web API, reducing the need for external tools.
- Focus on OpenAPI: The team wants to make OpenAPI a more first-class citizen in ASP.NET Core. They plan to extend the capabilities of
Microsoft.AspNetCore.OpenApito provide OpenAPI document generation without relying on external packages. - Alternative Tools: Visual Studio now offers built-in support for .http files and the new Endpoints Explorer, providing alternative ways to explore, test, and debug APIs.
- Community-Driven Innovation: By removing the default dependency, the team encourages the use and development of various OpenAPI tools that might better suit specific project needs.
An alternative to swagger : Scalar
Scalar is interactive API documentation from OpenAPI/Swagger documents.
You can get more information here.
How to use it in Dotnet 9
1 - installation
dotnet add package Scalar.AspNetCore 2 - example usage
using Scalar.AspNetCore; var builder = WebApplication.CreateBuilder(args); builder.Services.AddOpenApi(); var app = builder.Build(); if (app.Environment.IsDevelopment()) { app.MapScalarApiReference(); // scalar/v1 app.MapOpenApi(); } app.MapGet("/", () => "Hello world!"); app.Run(); When you run the application, you can access the API documentation at the scalar/v1 endpoint.
How to add Bearer authentication scheme to Scalar ?
Here is an example transformer for Bearer authentication:
public sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider): IOpenApiDocumentTransformer { public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken) { var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync(); if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer")) { // Add the security scheme at the document level var requirements = new Dictionary < string, OpenApiSecurityScheme > { ["Bearer"] = new OpenApiSecurityScheme { Type = SecuritySchemeType.Http, Scheme = "bearer", // "bearer" refers to the header name here In = ParameterLocation.Header, BearerFormat = "Json Web Token" } }; document.Components ??= new OpenApiComponents(); document.Components.SecuritySchemes = requirements; // Apply it as a requirement for all operations foreach(var operation in document.Paths.Values.SelectMany(path => path.Operations)) { operation.Value.Security.Add(new OpenApiSecurityRequirement { [new OpenApiSecurityScheme { Reference = new OpenApiReference { Id = "Bearer", Type = ReferenceType.SecurityScheme } }] = Array.Empty < string > () }); } } } } Example usage
builder.Services.AddOpenApi(opt => { opt.UseTransformer<BearerSecuritySchemeTransformer>(); }); 
Top comments (0)