an alternative to swagger in dotnet 9

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:

1. 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.
2. 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.
3. 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.OpenApi to provide OpenAPI document generation without relying on external packages.
4. 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.
5. 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>();
});

src: https://eminvergil.vercel.app/blog/scalar