scalar

Scalar 技能

Scalar 在此代码库中替代 Swagger/Swashbuckle，作为 OpenAPI 文档 UI。所有服务都使用 .NET 10 内置的 AddOpenApi()，并通过 Scalar 的 MapScalarApiReference() 提供 UI。项目要求所有微服务统一使用 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 挂载 Scalar UI	参见上面的示例
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 参考配置流畅 API”