Intent.AspNetCore.Scalar

The Intent.AspNetCore.Scalar module provides a modern, high-performance OpenAPI documentation interface using the Scalar library. Scalar offers a sleek, responsive alternative to Swagger UI with improved user experience and performance.

Overview

Scalar is a modern API documentation tool that generates beautiful, interactive documentation from your OpenAPI specifications. It provides a superior user experience compared to traditional Swagger UI with features like:

Fast, responsive interface
Modern, clean design
Built-in authentication testing
Better request/response visualization
Enhanced code generation

What Gets Generated

OpenApiConfiguration

Configures Scalar for your ASP.NET Core application:

public static class OpenApiConfiguration
{
    public static IServiceCollection AddOpenApi(this IServiceCollection services)
    {
        services.AddOpenApi(options =>
        {
            options.AddDocumentTransformer((document, context, cancellationToken) =>
            {
                document.Info = new OpenApiInfo
                {
                    Title = "My API",
                    Version = "v1",
                    Description = "API documentation"
                };
                return Task.CompletedTask;
            });

            // Add operation transformers
            options.AddOperationTransformer<HideRouteParametersFromBodyOperationTransformer>();
        });

        return services;
    }

    public static IApplicationBuilder UseScalarUi(this IApplicationBuilder app)
    {
        app.MapScalarApiReference(options =>
        {
            options.WithTitle("My API Documentation")
                   .WithTheme(ScalarTheme.Default)
                   .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);
        });

        return app;
    }
}

HideRouteParametersFromBodyOperationTransformer

Prevents route parameters from appearing in request bodies:

public class HideRouteParametersFromBodyOperationTransformer 
    : IOpenApiOperationTransformer
{
    public Task TransformAsync(
        OpenApiOperation operation,
        OpenApiOperationTransformerContext context,
        CancellationToken cancellationToken)
    {
        if (operation.Parameters == null)
            return Task.CompletedTask;

        var routeParameters = context.Description.ParameterDescriptions
            .Where(p => p.Source == BindingSource.Path)
            .Select(p => p.Name)
            .ToHashSet();

        // Remove route parameters from request body schemas
        if (operation.RequestBody?.Content != null)
        {
            foreach (var content in operation.RequestBody.Content.Values)
            {
                if (content.Schema?.Properties != null)
                {
                    foreach (var param in routeParameters)
                    {
                        content.Schema.Properties.Remove(param);
                    }
                }
            }
        }

        return Task.CompletedTask;
    }
}

Key Features

Modern UI

Clean, responsive design built with modern web standards

Fast Performance

Optimized for speed and smooth interactions

Code Generation

Generate client code in multiple languages

Dark Mode

Built-in dark mode support

Module Settings

Authentication

select

default:"None"

Configure the Scalar security schemeOptions:

None - No authentication
Bearer - JWT Bearer token authentication
Implicit - OAuth 2.0 Implicit flow

Use Fully Qualified Schema Identifiers

Use fully qualified schema identifiers

boolean

default:"true"

Use fully qualified type names for schema identifiersExample:

true: MyApp.Api.Dtos.ProductDto
false: ProductDto

Accessing Scalar UI

Once configured, access the Scalar documentation at:

https://localhost:5001/scalar/v1

The OpenAPI specification is available at:

https://localhost:5001/openapi/v1.json

Scalar vs Swagger UI

Feature	Scalar	Swagger UI
Performance	Faster, more responsive	Standard performance
UI/UX	Modern, clean design	Traditional interface
Dark Mode	Built-in	Requires customization
Code Generation	Multiple languages with better UX	Basic code samples
Request Testing	Enhanced with history	Standard functionality
Learning Curve	Intuitive	Familiar to most developers
Customization	Modern theming options	Extensive but dated

Authentication Configuration

When authentication is configured, Scalar provides a streamlined auth experience:

Bearer Token

services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Components ??= new OpenApiComponents();
        document.Components.SecuritySchemes.Add("Bearer", new OpenApiSecurityScheme
        {
            Type = SecuritySchemeType.Http,
            Scheme = "bearer",
            BearerFormat = "JWT",
            Description = "Enter your JWT token"
        });

        document.SecurityRequirements.Add(new OpenApiSecurityRequirement
        {
            [new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            }] = Array.Empty<string>()
        });

        return Task.CompletedTask;
    });
});

OAuth 2.0 Implicit Flow

document.Components.SecuritySchemes.Add("OAuth2", new OpenApiSecurityScheme
{
    Type = SecuritySchemeType.OAuth2,
    Flows = new OpenApiOAuthFlows
    {
        Implicit = new OpenApiOAuthFlow
        {
            AuthorizationUrl = new Uri("https://auth.example.com/authorize"),
            Scopes = new Dictionary<string, string>
            {
                ["read"] = "Read access",
                ["write"] = "Write access"
            }
        }
    }
});

Customizing Scalar

Configure Scalar’s appearance and behavior:

app.MapScalarApiReference(options =>
{
    options
        .WithTitle("My API")
        .WithTheme(ScalarTheme.Default) // or ScalarTheme.Dark, ScalarTheme.Light
        .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient)
        .WithDarkMode(true)
        .WithSearchHotKey("k");
});

Code Generation

Scalar provides enhanced code generation for multiple languages:

C# HttpClient
JavaScript Fetch
cURL

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", "your-token");

var response = await client.GetAsync(
    "https://api.example.com/products/123");
var product = await response.Content
    .ReadFromJsonAsync<ProductDto>();

const response = await fetch('https://api.example.com/products/123', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-token',
    'Content-Type': 'application/json'
  }
});
const product = await response.json();

curl -X GET "https://api.example.com/products/123" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json"

Request History

Scalar maintains a history of API requests made through the UI:

View previous requests
Replay requests with one click
Edit and resend modified requests
Export request collections

Migration from Swagger UI

To migrate from Swashbuckle to Scalar:

Remove Swashbuckle

Uninstall the Intent.AspNetCore.Swashbuckle module

Install Scalar

Install the Intent.AspNetCore.Scalar module

Update URLs

Update any documentation links to point to /scalar/v1 instead of /swagger

Test

Verify all endpoints are properly documented

XML Documentation

Scalar automatically includes XML documentation comments:

/// <summary>
/// Retrieves a product by its unique identifier
/// </summary>
/// <param name="id">The product ID</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The product details</returns>
/// <response code="200">Product found successfully</response>
/// <response code="404">Product not found</response>
[HttpGet("{id}")]
public async Task<ActionResult<ProductDto>> GetById(
    [FromRoute] Guid id,
    CancellationToken cancellationToken)
{
    // Implementation
}

Ensure XML documentation generation is enabled:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Installation

Intent.AspNetCore.Scalar

Dependencies

Intent.Common.CSharp
Intent.OutputManager.RoslynWeaver

Browser Support

Scalar works in all modern browsers:

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)

Next Steps

Controllers

Generate well-documented controllers

Versioning

Document multiple API versions

Security

Add authentication to your API

Swashbuckle

Compare with traditional Swagger UI

ASP.NET Core

API Documentation

Authentication & Security

API Features

Real-time Communication

Overview

What Gets Generated

OpenApiConfiguration

HideRouteParametersFromBodyOperationTransformer

Key Features

Modern UI

Fast Performance

Code Generation

Dark Mode

Module Settings

Authentication

Use Fully Qualified Schema Identifiers

Accessing Scalar UI

Scalar vs Swagger UI

Authentication Configuration

Bearer Token

OAuth 2.0 Implicit Flow

Customizing Scalar

Code Generation

Request History

Migration from Swagger UI

XML Documentation

Installation

Dependencies

Browser Support

Next Steps

Controllers

Versioning

Security

Swashbuckle

Build docs developers (and LLMs) love

ASP.NET Core

API Documentation

Authentication & Security

API Features

Real-time Communication

​Overview

​What Gets Generated

​OpenApiConfiguration

​HideRouteParametersFromBodyOperationTransformer

​Key Features

Modern UI

Fast Performance

Code Generation

Dark Mode

​Module Settings

​Authentication

​Use Fully Qualified Schema Identifiers

​Accessing Scalar UI

​Scalar vs Swagger UI

​Authentication Configuration

​Bearer Token

​OAuth 2.0 Implicit Flow

​Customizing Scalar

​Code Generation

​Request History

​Migration from Swagger UI

​XML Documentation

​Installation

​Dependencies

​Browser Support

​Next Steps

Controllers

Versioning

Security

Swashbuckle

Build docs developers (and LLMs) love

Overview

What Gets Generated

OpenApiConfiguration

HideRouteParametersFromBodyOperationTransformer

Key Features

Module Settings

Authentication

Use Fully Qualified Schema Identifiers

Accessing Scalar UI

Scalar vs Swagger UI

Authentication Configuration

Bearer Token

OAuth 2.0 Implicit Flow

Customizing Scalar

Code Generation

Request History

Migration from Swagger UI

XML Documentation

Installation

Dependencies

Browser Support

Next Steps