scalar

Scalar

核心原则

1. Scalar 替代 Swagger UI — Scalar 是 .NET 10 推荐的 API 文档 UI。渲染速度更快，内置深色模式，支持数十种语言的代码生成，并全面支持 OpenAPI 3.1。
2. 默认仅在开发环境中使用 — 将 MapScalarApiReference() 包装在 IsDevelopment() 检查中。API 文档会暴露内部结构。如果需要在生产环境中使用，请添加授权。
3. 对敏感 API 禁用代理 — Scalar 的“Try It”功能默认通过 proxy.scalar.com 路由。使用 .WithProxy(null) 禁用代理，以便将授权标头保留在本地。
4. 安全方案来自 OpenAPI — Scalar 从 OpenAPI 文档中读取安全方案。请通过文档转换器进行配置，不要直接在 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);
});

预填身份验证信息（仅限开发环境）

预填凭据，开发者就不必手动粘贴令牌。OpenAPI 文档必须已通过文档转换器包含安全方案。

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

其他身份验证类型：

// API Key
options.WithApiKeyAuthentication(apiKey =>
{
    apiKey.Token = "dev-api-key";
});

// OAuth2
options.WithOAuth2Authentication(oauth =>
{
    oauth.ClientId = "your-client-id";
    oauth.Scopes = ["openid", "profile"];
});

可用主题

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

多个 API 文档

// Register multiple OpenAPI documents
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2-beta");

// Scalar picks them up automatically
app.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 production
app.MapOpenApi().RequireAuthorization("ApiDocs");
app.MapScalarApiReference().RequireAuthorization("ApiDocs");

强制使用深色模式

options.ForceDarkMode();

经典布局（类似 Swagger）

options.WithClassicLayout();

反模式

不要在生产环境中无授权地公开 Scalar

// BAD — anyone can see your API structure
app.MapOpenApi();
app.MapScalarApiReference();

// GOOD — development only
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

// GOOD — production with auth
app.MapOpenApi().RequireAuthorization("ApiDocs");
app.MapScalarApiReference().RequireAuthorization("ApiDocs");

不要预填真实凭据

// BAD — real tokens visible in browser
options.AddHttpAuthentication("Bearer", auth =>
{
    auth.Token = "eyJhbG...real-production-token";
});

// GOOD — dev-only test tokens
if (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 schemes
builder.Services.AddOpenApi();
app.MapScalarApiReference(options =>
{
    options.WithPreferredScheme("Bearer"); // Does nothing!
});

// GOOD — register the document transformer first
builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});
app.MapScalarApiReference(options =>
{
    options.WithPreferredScheme("Bearer");
});

不要为敏感 API 保持代理启用

// BAD — auth headers flow through proxy.scalar.com
app.MapScalarApiReference();

// GOOD — disable proxy for APIs with sensitive data
app.MapScalarApiReference(options =>
{
    options.WithProxy(null);
});

新建 .NET 10 项目时不要使用 Swagger UI

// BAD — Swashbuckle removed from templates, maintenance concerns
builder.Services.AddSwaggerGen();
app.UseSwaggerUI();

// GOOD — built-in OpenAPI + Scalar
builder.Services.AddOpenApi();
app.MapOpenApi();
app.MapScalarApiReference();

决策指南

场景	建议
API 文档 UI	使用 MapScalarApiReference() 和 MapOpenApi()
开发环境	使用带 IsDevelopment() 防护的默认设置
生产环境 API 文档	为两个端点都添加 .RequireAuthorization()
在开发环境中测试身份验证	使用 AddHttpAuthentication() 配合测试令牌
偏好深色主题	使用 .ForceDarkMode() 或 .WithTheme(ScalarTheme.Moon)
多个 API 版本	多次调用 AddOpenApi() — Scalar 会自动检测
敏感 API	使用 .WithProxy(null) 禁用外部代理
类似 Swagger 的布局	使用 .WithClassicLayout()
自定义路由	使用 app.MapScalarApiReference("/api-docs")