Scalar .NET API Reference Integration

This .NET package Scalar.AspNetCore provides an easy way to render beautiful API references based on OpenAPI/Swagger documents.

Made possible by the wonderful work of @captainsafia on building the integration and docs written for the Scalar & .NET integration. Thanks to @xC0dex for making it awesome.

Features

• Stunning API Reference
• Compatible with .NET 8 and above
• Independent of OpenAPI document generators
• Fully AOT (Ahead-of-Time) compatible

Migration Guide

If you are upgrading from 2.1.x to 2.2.x, please refer to the migration guide. If you are upgrading from 1.x.x to 2.x.x, please refer to the migration guide.

Usage

1. Install the package

dotnet add package Scalar.AspNetCore

2. Add the using directive

using Scalar.AspNetCore;

3. Configure your application

Add the following to Program.cs based on your OpenAPI generator:

For Microsoft.AspNetCore.OpenApi:

builder.Services.AddOpenApi();

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

For Swashbuckle:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger(options =>
    {
        options.RouteTemplate = "/openapi/{documentName}.json";
    });
    app.MapScalarApiReference();
}

For NSwag:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument();

if (app.Environment.IsDevelopment())
{
    app.UseOpenApi(options =>
    {
        options.Path = "/openapi/{documentName}.json";
    });
    app.MapScalarApiReference();
}

For FastEndpoints:

builder.Services.SwaggerDocument();

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerGen(options =>
    {
        options.Path = "/openapi/{documentName}.json";
    });
    app.MapScalarApiReference();
}

You’re all set! 🎉 Visit /scalar to see the API Reference for the default OpenAPI document (v1).

If you have multiple OpenAPI documents, you can set them up with AddDocument or AddDocuments (see Multiple OpenAPI Documents).
To view a specific document, go to /scalar/{documentName} (like /scalar/v1 or /scalar/v2-beta).

Configuration

For detailed configuration options, refer to the integration documentation. This documentation focuses on the features provided by the package.

For more realistic examples and advanced usage scenarios, such as authentication, API versioning, and handling multiple documents, check out our extended examples documentation. This documentation is also useful if you need more context on what Scalar.AspNetCore is for.

OpenAPI extensions

Scalar provides additional packages to enhance OpenAPI document generation:

• Scalar.AspNetCore.Microsoft: Implements transformers for Microsoft.AspNetCore.OpenApi
• Scalar.AspNetCore.Swashbuckle: Implements filters for Swashbuckle

These packages enable advanced features like stability indicators and API Reference exclusions. See the dotnet integration documentation for details.

Development

Local

1. Download .NET 9.0
2. Jump to the package folder: cd integrations/aspnetcore
3. Do a fresh build: dotnet build
4. Run the tests: dotnet test

And see it in action here:

1. Switch to the playground: cd playground/Scalar.AspNetCore.Playground
2. Start the playground: dotnet run
3. Open this URL in the browser: http://localhost:5056/scalar/

Docker

If you don't have the SDK installed or want to run the playground under a subpath, you can use Docker Compose:

1. Run Docker Compose: docker compose up --build
2. Open this URL in the browser: http://localhost:8080/api/scalar/

Community

We are API nerds. You too? Let’s chat on Discord: https://discord.gg/scalar

License

The source code in this repository is licensed under MIT.