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)