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	MapOpenApi() と併せて MapScalarApiReference() を使用
開発環境	IsDevelopment() ガードを使ったデフォルト設定
本番環境の API ドキュメント	両方のエンドポイントに .RequireAuthorization() を追加
開発環境での認証テスト	テスト用トークンを使って AddHttpAuthentication() を使用
ダークテーマを使用する場合	.ForceDarkMode() または .WithTheme(ScalarTheme.Moon)
複数の API バージョン	複数の AddOpenApi() 呼び出し — Scalar が自動的に検出
機密性の高い API	.WithProxy(null) で外部プロキシを無効化
Swagger 風のレイアウト	.WithClassicLayout()
カスタムルート	app.MapScalarApiReference("/api-docs")