Configuring Scalar API Reference in ASP.NET Core

Introduction

Scalar is a modern, interactive API reference tool that provides a clean and customizable interface for exploring your ASP.NET Core Web API endpoints. It integrates seamlessly with OpenAPI specifications, offering features like request testing, code samples, and theming. This guide walks you through integrating Scalar into your ASP.NET Core Web API project, from installing the necessary package to launching the reference UI.

What You Need

• ASP.NET Core Web API project – created using the default template (e.g., dotnet new webapi).
• .NET SDK (version 8.0 or later recommended).
• An IDE or code editor – Visual Studio, Visual Studio Code, or JetBrains Rider.
• Basic familiarity with C# and ASP.NET Core – comfortable editing launchSettings.json and Program.cs.

Step-by-Step Instructions

Step 1: Install the Scalar NuGet Package

The first step is to add the Scalar.AspNetCore NuGet package to your project. This package provides the middleware and UI components for rendering the API reference.

You can install it using the .NET CLI, the Package Manager Console, or the NuGet Package Manager in your IDE.

Using .NET CLI:

dotnet add package Scalar.AspNetCore

Using Package Manager Console (Visual Studio):

Install-Package Scalar.AspNetCore

Alternatively, right-click your project in Solution Explorer, select “Manage NuGet Packages”, search for Scalar.AspNetCore, and click Install.

Once installed, verify the package reference in your .csproj file. It should look similar to this:

<PackageReference Include="Scalar.AspNetCore" Version="1.2.3" />

Step 2: Configure launchSettings.json

To make your browser automatically open the Scalar UI when you run the project, update the Properties/launchSettings.json file. This file defines how the application launches in different profiles (e.g., http, https).

Open the file and locate the profile you intend to use (commonly http or a named profile). Add or modify two settings:

• "launchBrowser": true – instructs the IDE to open a browser automatically.
• "launchUrl": "scalar" – sets the URL path to /scalar where the Scalar UI will be served.

Here is an example snippet for the http profile:

{
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "scalar",
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Save the file. Note: You may need to restart your IDE if it caches the settings.

Step 3: Add Scalar Middleware in Program.cs

Now you need to register the Scalar middleware in your application's pipeline. This is done in the Program.cs file, typically inside a development-only check to avoid exposing the reference in production.

First, ensure your project already has OpenAPI support enabled. The default ASP.NET Core Web API template includes AddOpenApi() and MapOpenApi() calls. If not, add them:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();

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

app.Run();

Then, inside the same development block, add the Scalar endpoint:

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

The MapScalarApiReference() call registers the Scalar UI at the default endpoint /scalar (matching the launchUrl you set earlier). For custom configuration, you can pass options like a different route or theme. For example:

app.MapScalarApiReference(options => {
    options.WithTitle("My API");
    options.WithTheme(ScalarTheme.Kepler);
});

But the default configuration works fine for basic use.

Step 4: Run the Project

You are now ready to test the integration. Press Ctrl+F5 (or click “Run”) to start the application without debugging, or F5 with debugging. Because you set launchBrowser to true, your default browser will open automatically to the /scalar URL.

If everything is set up correctly, you will see the Scalar API reference page, listing all your API endpoints. You can expand each endpoint, view request/response schemas, and even send test requests directly from the UI.

If the browser opens but shows a blank page or an error, check the following:

• Make sure your application is running in Development mode (ASPNETCORE_ENVIRONMENT=Development).
• Verify that the OpenAPI endpoint is accessible (e.g., navigate to /openapi/v1.json or whatever route you configured).
• Check the console output for any errors related to Scalar or OpenAPI.

Tips for a Smooth Experience

• Keep OpenAPI enabled – Scalar relies on the OpenAPI JSON document generated by MapOpenApi(). Ensure that endpoint is not disabled.
• Customize the Scalar theme – Scalar supports multiple themes (like ScalarTheme.Kepler, ScalarTheme.Mars). Pass them via the options delegate for a branded look.
• Protect in production – Always guard Scalar behind the IsDevelopment() check or add authentication/authorization to prevent exposing internal API details.
• Use HTTPS – If your project is set up with HTTPS, consider using it to avoid mixed-content issues in Scalar (e.g., when the browser loads resources).
• Check for package updates – Scalar is actively developed; periodically update the NuGet package to get new features and fixes.
• Explore advanced options – You can configure Scalar to hide deprecated endpoints, add custom code samples, or embed it in your own HTML page. Refer to the official Scalar documentation for more.

With these steps, you now have a fully functional Scalar API reference integrated into your ASP.NET Core Web API. This tool makes it much easier to document, test, and share your endpoints with team members or consumers.