scalar

Scalar スキル

Scalar は、このコードベースの OpenAPI ドキュメント UI として Swagger/Swashbuckle に代わるものです。すべてのサービスで、.NET 10 に組み込まれている AddOpenApi() と、UI に使用する Scalar の MapScalarApiReference() を使います。このプロジェクトでは、すべてのマイクロサービスで Purple テーマを統一して使用します。

クイックスタート

標準的なサービスの設定

// Program.cs - Service setup
builder.Services.AddOpenApi();

var app = builder.Build();
app.MapOpenApi();

if (app.Environment.IsDevelopment())
{
    app.MapScalarApiReference(options =>
    {
        options
            .WithTitle("Blueprint Service")
            .WithTheme(ScalarTheme.Purple)
            .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);
    });
}

ドキュメントを集約する API ゲートウェイ

// Aggregated OpenAPI from all services
app.MapGet("/openapi/aggregated.json", async (OpenApiAggregationService service) =>
{
    var spec = await service.GetAggregatedOpenApiAsync();
    return Results.Json(spec);
})
.ExcludeFromDescription();

app.MapScalarApiReference(options =>
{
    options
        .WithTitle("Sorcha API Gateway - All Services")
        .WithTheme(ScalarTheme.Purple)
        .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient)
        .WithOpenApiRoutePattern("/openapi/aggregated.json");
});

主な概念

概念	用途	例
AddOpenApi()	OpenAPI サービスを登録する	builder.Services.AddOpenApi()
MapOpenApi()	/openapi/v1.json を公開する	app.MapOpenApi()
MapScalarApiReference()	Scalar UI を /scalar にマウントする	上記の例を参照
ScalarTheme	ビジュアルテーマの列挙型	ScalarTheme.Purple
ScalarTarget	コード生成ターゲット	ScalarTarget.CSharp
ScalarClient	HTTP クライアントライブラリ	ScalarClient.HttpClient

よくあるパターン

Scalar 用のエンドポイントをドキュメント化する

app.MapPost("/api/wallets", handler)
    .WithName("CreateWallet")
    .WithSummary("Create a new wallet")
    .WithDescription("Creates an HD wallet with the specified algorithm")
    .WithTags("Wallets");

Markdown を使った詳細な OpenAPI の説明

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, ct) =>
    {
        document.Info.Title = "Register Service API";
        document.Info.Version = "1.0.0";
        document.Info.Description = """
            # Register Service
            
            ## Overview
            Provides a **distributed ledger** for immutable transactions.
            
            ## Key Features
            - Cryptographic signatures
            - Chain integrity verification
            """;
        return Task.CompletedTask;
    });
});

関連項目

• パターン
• ワークフロー

関連スキル

• エンドポイントのドキュメント化パターンについては minimal-apis スキルを参照してください
• サービス検出との統合については aspire スキルを参照してください
• API ゲートウェイの設定については yarp スキルを参照してください

ドキュメントリソース

Context7 を使って最新の Scalar ドキュメントを取得します。

Context7 の使い方：

1. mcp__context7__resolve-library-id を使って「scalar」を検索します
2. ソースリポジトリよりもウェブサイトのドキュメント（/websites/guides_scalar）を優先します
3. 解決したライブラリ ID を使い、mcp__context7__query-docs でクエリを実行します

ライブラリ ID： /websites/guides_scalar

推奨クエリ：

• 「Scalar .NET ASP.NET Core の設定オプション、テーマ」
• 「Scalar で利用可能なテーマ、ダークモードのカスタマイズ」
• 「Scalar API リファレンスの設定、fluent API」