API Documentation with Scalar in ASP .NET Core

Introduction

In contemporary web development, having API documentation that is both well-structured and visually appealing is crucial. Scalar is an excellent tool for generating attractive API documentation for ASP.NET Core applications. This article will explore how to effortlessly integrate Scalar into an ASP.NET Core project and create API documentation.

What is Scalar?

Scalar is an open-source API documentation tool that provides an intuitive and visually appealing interface for exploring and testing APIs. It is an alternative to Swagger UI and Redoc, offering simplicity and ease of use.

Why Use Scalar for API Documentation?

• User-friendly Interface: Scalar provides a clean and modern UI.
• Interactive API Testing: Allows developers to test APIs directly from the documentation.
• Easy Integration: Simple setup process with minimal configuration.
• Open Source: Free to use and modify according to project needs.

Setting Up Scalar in ASP.NET Core

Step 1. Install Scalar Package.

To integrate Scalar into your ASP.NET Core project, you need to install the Scalar NuGet package. Run the following command in the terminal.

Install-Package Scalar.AspNetCore

Step 2. Configure Scalar in Startup.cs.

Modify the Startup.cs file to add Scalar middleware.

using Scalar.AspNetCore;

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddScalar();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });

    app.UseScalar(); // Enable Scalar documentation
}

Step 3. Access API Documentation.

Once the configuration is complete, run your ASP.NET Core application and navigate to the following URL.

https://localhost:<port>/scalar

You should see a beautifully generated API documentation interface.

Customizing Scalar Documentation

Scalar provides customization options to enhance the API documentation experience.

1. Adding API Metadata

You can customize API metadata such as title, version, and description by modifying the Scalar configuration.

services.AddScalar(options =>
{
    options.DocumentTitle = "My API Documentation";
    options.ApiVersion = "v1.0";
    options.Description = "This is a sample API documentation using Scalar.";
});

2. Securing API Documentation

To restrict access to your API documentation, you can implement authentication middleware to protect the Scalar endpoint.

Conclusion

Scalar is a powerful tool for creating beautiful and interactive API documentation in ASP.NET Core. With its ease of integration, user-friendly interface, and customization options, it is an excellent alternative to traditional documentation tools like Swagger. By following the steps outlined in this article, you can quickly set up Scalar and improve your API documentation experience.