With the latest release of .NET, you will notice that new WebApi projects no longer integrate with Swagger to provide a documentation web page.
In .NET 9, Microsoft made a strategic decision to remove the default inclusion of Swashbuckle.AspNetCore (commonly known as Swagger) from Web API project templates. This shift is primarily due to the following reasons:
- Maintenance Challenges: Swashbuckle, a popular third-party library for generating OpenAPI documentation, has faced maintenance issues. The original maintainer stepped back, leading to unresolved issues and a lack of official releases for newer .NET versions, notably .NET 8.
- Native OpenAPI Support: To ensure consistent and up-to-date API documentation, Microsoft introduced built-in OpenAPI capabilities within the .NET framework. This native support reduces reliance on external dependencies and aligns more closely with the evolving .NET ecosystem.
- Introduction of Scalar: Alongside native OpenAPI support, Microsoft unveiled Scalar, a modern and intuitive API documentation tool. Scalar offers a fresh interface and enhanced features, providing a seamless experience for developers interacting with API documentation.
By transitioning to these integrated tools, Microsoft aims to provide a more streamlined, reliable, and cohesive approach to API documentation in .NET 9, addressing previous limitations and enhancing the developer experience.
Here’s how we can enable and use Scalar in .NET 9 WebApi projects:
1. Install the Scalar.AspNetCore Package
Begin by adding the Scalar.AspNetCore package to your project. This package facilitates the integration of Scalar with ASP.NET Core applications. You can install it using the following command:
dotnet add package Scalar.AspNetCore --version 2.0.*
The wildcard in the version ensures you get the latest patch updates within the 2.0 release.
You can also install this package via the NuGet Package Manager UI by searching for Scalar.AspNetCore:
2. Update Program.cs
Modify your Program.cs to configure OpenAPI services and integrate Scalar. Here’s how you can do it:
using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.MapScalarApiReference();
}
app.UseHttpsRedirection();
var summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapGet("/weatherforecast", () =>
{
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
(
DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
Random.Shared.Next(-20, 55),
summaries[Random.Shared.Next(summaries.Length)]
))
.ToArray();
return forecast;
})
.WithName("GetWeatherForecast");
app.Run();
internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
In this setup:
builder.Services.AddOpenApi();registers the necessary OpenAPI services.app.MapOpenApi();sets up the OpenAPI endpoint.app.MapScalarApiReference();integrates the Scalar UI for interactive API documentation.
This configuration ensures that Scalar is available in the development environment.
Note: this Program.cs file contains the source code for the default WebApi MinimalApi project type. It contains a simple WeatherForecast service which is useful to show how Scalar renders your WebApi documentation.
3. Access the Scalar UI
After running your application, navigate to /scalar/v1 (e.g., https://localhost:5001/scalar/v1) in your browser to access the Scalar UI. This interface provides an interactive view of your API endpoints, enhancing the developer experience.
4. Launch Settings Changes
To simplify launching your WebApi project, you can change the lauchSettings.json file to always open a browser to the Scalar page. Make the following changes to your launchSettings.json file:
{
"$schema": "https://json.schemastore.org/launchsettings.json",
"profiles": {
"http": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "http://localhost:5047",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"https": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://localhost:7181;http://localhost:5047",
"launchUrl": "scalar/v1",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
Lines 7 and 16 set the project to open the user’s browser when this project is launched for debugging. Line 18 sets the launch url to include the path to the scalar UI page. By having this in your project, you will mimic the behavior of Swagger UI in older .NET projects.
5. Customize Scalar (Optional)
Scalar offers customization options to tailor the UI to your preferences. You can adjust settings such as the title and sidebar visibility:
app.MapScalarApiReference(options =>
{
options.WithTitle("Custom API Documentation");
options.WithSidebar(false);
});
This customization allows you to provide a personalized documentation experience. There are many different customization options available, so you should experiment with them.
Conclusion
While Scalar is a powerful tool for development, it’s essential to consider security implications when exposing API documentation in production environments. Ensure that sensitive information is protected and that the documentation is accessible only to authorized users. Or as we have done in article, you can launch include the API documentation only when running your service in development or test environments.
By following these steps, you can seamlessly integrate Scalar into your .NET 9 Minimal API project, providing an enhanced and interactive documentation experience for your APIs.
DarthPedro's Blog 