Scalar, the new standard for API documentation 🚀

Introduction

Swagger (now known as OpenAPI) has long been the standard for API documentation in .NET applications.
However, Scalar, a lightweight and efficient API documentation framework, is gaining traction due to its simplicity and performance benefits. In fact, it even has been pushed to the front scene by Microsoft with .NET 9 and recommended to be used as the default API documentation framework ! 🥹
So this little guide will introduce Scalar, compare it with Swagger, and provide a detailed step-by-step approach to migrating from Swagger to Scalar in a .NET API. 📜

Why Choose Scalar Over Swagger ? 🌟

Scalar is a modern API documentation tool tailored for .NET applications. It offers several advantages over Swagger:

• Faster Load Times: Scalar optimizes API documentation rendering for improved performance.
• Lower Overhead: Reduces JSON serialization load, making APIs more efficient.
• Simpler UI: Provides a clean, dark (oh god yes) and intuitive interface for API exploration.
• Better Performance for Large APIs: Unlike Swagger, which can become sluggish when dealing with large APIs, Scalar remains lightweight and fast.
• Easier Configuration: Scalar requires fewer dependencies and simpler setup than Swagger. 🔧

If your project requires a lightweight and efficient documentation tool, Scalar could be a great alternative. ✅

Prerequisites

Before starting the migration, ensure you have:

• A .NET API project currently using Swagger for documentation.
• .NET 8 or later installed.
• The dotnet CLI available or a dotnet IDE.
• Basic knowledge of middleware configuration in .NET Core.

Step-by-Step Migration

Remove Swagger Dependencies

First, uninstall Swagger from your project. If you’re using Swashbuckle, remove the NuGet package:

 dotnet remove package Swashbuckle.AspNetCore

Next, delete any Swagger configuration from Program.cs or Startup.cs. Look for and remove the following lines:

app.UseSwagger();
app.UseSwaggerUI();

Additionally, remove any Swagger-related configuration sections such as:

builder.Services.AddSwaggerGen();

If you have a SwaggerConfig class or any custom middleware related to Swagger, remove those as well.

Once Swagger is fully removed, clean and rebuild your project to ensure no lingering dependencies:

 dotnet clean
 dotnet build

or clean & build with your IDE.

Install Scalar

Now, install Scalar by adding the required NuGet package:

 dotnet add package Scalar.AspNetCore

Once installed, ensure your project restores dependencies:

 dotnet restore

Configure Scalar

Modify Program.cs to integrate Scalar. Find the section where middleware is configured and add Scalar:

using Scalar.AspNetCore;

namespace WebApplication1;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddControllers();

        // Add Open API services
        builder.Services.AddOpenApi();

        var app = builder.Build();

        // Configure the HTTP request pipeline.
        if (app.Environment.IsDevelopment())
        {
            app.MapOpenApi();
            
            // Maps scalar to the default endpoint /scalar
            app.MapScalarApiReference();
        }

        app.UseHttpsRedirection();

        app.UseAuthorization();


        app.MapControllers();

        app.Run();
    }
}

Customize Scalar Settings

Scalar allows customization of its UI and behavior. To configure options, you can use the lambda opt inside the MapScalarApiReference() method:

There are many parameters available, so feel free to custom those as you need !

Verify Scalar Integration

Once the changes are made, build and run your application:

 dotnet build
 dotnet run

Check the console output for any errors related to missing dependencies or misconfiguration.
In our tutorial we are using the default WeatherForecast WebApi template from .NET 9, but in a bigger project with specific and custom configuration you may have some more fixes to do !

Access the Scalar UI 🌐

With the application running, open your browser and navigate to:

http://localhost:5194/scalar

If your app is configured to use a different port, adjust the URL accordingly. You should now see your API documentation generated by Scalar. 🌟
Scalar will then list each of your endpoints.

To send a request, simply click on the “Test Request” button:

And then on “Send” button to send a request to your local endpoint:

Just like Swagger, you’ll see infos about the response in the same modal ! 💫

Conclusion

Migrating from Swagger to Scalar in a .NET API is a straightforward process that improves performance and simplifies API documentation.
By following these steps, you can seamlessly transition to Scalar and take advantage of its efficiency and ease of use. ✅

Scalar provides a sleek, modern UI with enhanced performance benefits, making it an excellent choice for developers looking to streamline API documentation. If you need more customization, Scalar also offers various themes and settings that can be fine-tuned to meet your project’s needs. 💡

For more details, refer to the official Scalar documentation .

As always, Happy hacking 👨‍💻❤️