Scalar

using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder(args);builder.Services.AddOpenApi();
var app = builder.Build();
if (app.Environment.IsDevelopment()){    app.MapOpenApi();    app.MapScalarApiReference();  // UI at /scalar/v1}
app.Run();

app.MapScalarApiReference(options =>{    options        .WithTitle("Checkout API")        .WithTheme(ScalarTheme.Mars)        .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient)        .WithPreferredScheme("Bearer")        .WithProxy(null)  // Disable external proxy        .WithSidebar(true);});

if (app.Environment.IsDevelopment()){    app.MapScalarApiReference(options =>    {        options            .WithPreferredScheme("Bearer")            .AddHttpAuthentication("Bearer", auth =>            {                auth.Token = "dev-only-test-token";            });    });}

// API Keyoptions.WithApiKeyAuthentication(apiKey =>{    apiKey.Token = "dev-api-key";});
// OAuth2options.WithOAuth2Authentication(oauth =>{    oauth.ClientId = "your-client-id";    oauth.Scopes = ["openid", "profile"];});

// ScalarTheme options: Default, Moon, Purple, BluePlanet, Saturn, Mars, DeepSpace, Kepler, Solarized, Laserwaveoptions.WithTheme(ScalarTheme.Mars);

// Register multiple OpenAPI documentsbuilder.Services.AddOpenApi("v1");builder.Services.AddOpenApi("v2-beta");
// Scalar picks them up automaticallyapp.MapOpenApi();app.MapScalarApiReference();// Available at /scalar/v1 and /scalar/v2-beta

app.MapScalarApiReference(options =>{    options        .AddDocument("v1", "Production API")        .AddDocument("v2-beta", "Beta API", isDefault: true);});

// Default is /scalar/{documentName}app.MapScalarApiReference("/api-docs");// Now at /api-docs/v1

// When partners need access to docs in productionapp.MapOpenApi().RequireAuthorization("ApiDocs");app.MapScalarApiReference().RequireAuthorization("ApiDocs");

options.ForceDarkMode();

options.WithClassicLayout();

// BAD — anyone can see your API structureapp.MapOpenApi();app.MapScalarApiReference();
// GOOD — development onlyif (app.Environment.IsDevelopment()){    app.MapOpenApi();    app.MapScalarApiReference();}
// GOOD — production with authapp.MapOpenApi().RequireAuthorization("ApiDocs");app.MapScalarApiReference().RequireAuthorization("ApiDocs");

// BAD — real tokens visible in browseroptions.AddHttpAuthentication("Bearer", auth =>{    auth.Token = "eyJhbG...real-production-token";});
// GOOD — dev-only test tokensif (app.Environment.IsDevelopment()){    options.AddHttpAuthentication("Bearer", auth =>    {        auth.Token = "dev-only-test-token";    });}

// BAD — no auth UI in Scalar because OpenAPI doc has no security schemesbuilder.Services.AddOpenApi();app.MapScalarApiReference(options =>{    options.WithPreferredScheme("Bearer"); // Does nothing!});
// GOOD — register the document transformer firstbuilder.Services.AddOpenApi(options =>{    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();});app.MapScalarApiReference(options =>{    options.WithPreferredScheme("Bearer");});

// BAD — auth headers flow through proxy.scalar.comapp.MapScalarApiReference();
// GOOD — disable proxy for APIs with sensitive dataapp.MapScalarApiReference(options =>{    options.WithProxy(null);});

// BAD — Swashbuckle removed from templates, maintenance concernsbuilder.Services.AddSwaggerGen();app.UseSwaggerUI();
// GOOD — built-in OpenAPI + Scalarbuilder.Services.AddOpenApi();app.MapOpenApi();app.MapScalarApiReference();