DEV Community

Cover image for Integrating Scalar API Documentation in ASP.NET Core
Adnan al-emran ontor
Adnan al-emran ontor

Posted on

Integrating Scalar API Documentation in ASP.NET Core

#api #csharp #dotnet #tutorial

Integrating Scalar API Documentation in ASP.NET Core

Modern APIs require clear and interactive documentation so developers can easily understand and test endpoints. Scalar is a modern API documentation UI built on top of OpenAPI, providing a clean and developer-friendly interface for exploring APIs.

In this article, we will integrate Scalar API Documentation into an ASP.NET Core Web API project.

What is Scalar?

Scalar is a modern API documentation tool designed for OpenAPI specifications. It allows developers to:

  • Explore API endpoints
  • View request and response schemas
  • Test APIs directly from the browser
  • Generate ready-to-use client code examples

Compared to traditional documentation tools, Scalar provides a more modern and intuitive user interface.

Step 1 — Install Scalar

Install the Scalar.AspNetCore NuGet package.

dotnet add package Scalar.AspNetCore --version 2.1.13
Enter fullscreen mode Exit fullscreen mode

Or install it from NuGet:

https://www.nuget.org/packages/Scalar.AspNetCore

Step 2 — Configure Services

Open Program.cs and register the required services.

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer(); // Required for OpenAPI generation
builder.Services.AddOpenApi();
Enter fullscreen mode Exit fullscreen mode

Explanation

  • AddControllers() enables controller-based APIs
  • AddEndpointsApiExplorer() generates API metadata
  • AddOpenApi() generates the OpenAPI specification used by Scalar

Step 3 — Configure the HTTP Pipeline

Add Scalar and OpenAPI to the request pipeline.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.MapScalarApiReference(options =>
    {
        options
            .WithTitle("ServerSide API")
            .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);
    });

    // Redirect root URL to Scalar documentation
    app.MapGet("/", () => Results.Redirect("/scalar/v1"))
        .ExcludeFromDescription();
}
Enter fullscreen mode Exit fullscreen mode

What this configuration does

  • MapOpenApi() exposes the OpenAPI JSON document
  • MapScalarApiReference() enables the Scalar documentation UI
  • WithTitle() sets the API documentation title
  • WithDefaultHttpClient() generates C# HttpClient examples
  • The root URL automatically redirects to the documentation page

Step 4 — Run the Application

Run the ASP.NET Core project and open the documentation in your browser:

http://localhost:5000/scalar/v1
Enter fullscreen mode Exit fullscreen mode

or

https://localhost:5001/scalar/v1
Enter fullscreen mode Exit fullscreen mode

You will see the interactive Scalar API documentation interface.

Benefits of Using Scalar

  • Modern API documentation interface
  • Built-in API testing
  • Automatic OpenAPI integration
  • Code examples for multiple programming languages
  • Easy integration with ASP.NET Core

Conclusion

Integrating Scalar API documentation into an ASP.NET Core project is simple and significantly improves the developer experience. With only a few lines of configuration, you can provide a powerful and interactive API documentation interface.

Scalar helps developers understand and test APIs more efficiently.

Author

Adnan Al Emran

Software Engineer

GitHub

https://github.com/adnanalemran

Top comments (0)