Back to Details

scalar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scalar Skill

Scalar 技能指南

Scalar replaces Swagger/Swashbuckle as the OpenAPI documentation UI in this codebase. All services use .NET 10's built-in 
AddOpenApi()
with Scalar's 
MapScalarApiReference()
for the UI. The project enforces Purple theme consistency across all microservices.
Scalar 在此代码库中替代 Swagger/Swashbuckle 作为 OpenAPI 文档 UI。所有服务均使用 .NET 10 内置的 
AddOpenApi()
搭配 Scalar 的 
MapScalarApiReference()
来实现该 UI。项目要求所有微服务统一使用 Purple 主题。

Quick Start

快速开始

Standard Service Configuration

标准服务配置

csharp
// 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);
    });
}
csharp
// 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 Gateway with Aggregated Documentation

带聚合文档的API网关

csharp
// 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");
});
csharp
// 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");
});

Key Concepts

核心概念

ConceptUsageExample
AddOpenApi()
Register OpenAPI services
builder.Services.AddOpenApi()
MapOpenApi()
Expose 
/openapi/v1.json
app.MapOpenApi()
MapScalarApiReference()
Mount Scalar UI at 
/scalar
See examples above
ScalarTheme
Visual theme enum
ScalarTheme.Purple
ScalarTarget
Code generation target
ScalarTarget.CSharp
ScalarClient
HTTP client library
ScalarClient.HttpClient
概念用途示例
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

Common Patterns

常见模式

Document Endpoints for Scalar

为Scalar文档化端点

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

Rich OpenAPI Descriptions with Markdown

带Markdown的丰富OpenAPI描述

csharp
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;
    });
});
csharp
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;
    });
});

See Also

另请参阅

  • patterns
  • workflows
  • 模式
  • 工作流

Related Skills

相关技能

  • See the minimal-apis skill for endpoint documentation patterns
  • See the aspire skill for service discovery integration
  • See the yarp skill for API Gateway configuration
  • 查看 minimal-apis 技能以了解端点文档模式
  • 查看 aspire 技能以了解服务发现集成
  • 查看 yarp 技能以了解API网关配置

Documentation Resources

文档资源

Fetch latest Scalar documentation with Context7.
How to use Context7:
  1. Use 
    mcp__context7__resolve-library-id
    to search for "scalar"
  2. Prefer website documentation (
    /websites/guides_scalar
    ) over source repositories
  3. Query with 
    mcp__context7__query-docs
    using the resolved library ID
Library ID: 
/websites/guides_scalar
Recommended Queries:
  • "Scalar .NET ASP.NET Core configuration options themes"
  • "Scalar themes available dark mode customization"
  • "Scalar API reference configuration fluent API"
使用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 configuration options themes"
  • "Scalar themes available dark mode customization"
  • "Scalar API reference configuration fluent API"