‫تولید API Documentation مدرن با Scalar در ASP.NET Core

dotnet add package Scalar.AspNetCore

using Scalar.AspNetCore;

builder.Services.AddOpenApi();
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

برای Swashbuckle.AspNetCore.SwaggerGen
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

if (app.Environment.IsDevelopment())
{
    app.MapSwagger("/openapi/{documentName}.json");
    app.MapScalarApiReference();
}

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument();

if (app.Environment.IsDevelopment())
{
    app.UseOpenApi(options =>
    {
        options.Path = "/openapi/{documentName}.json";
    });
    app.MapScalarApiReference();
}

builder.Services.SwaggerDocument();

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerGen(options =>
    {
        options.Path = "/openapi/{documentName}.json";
    });
    app.MapScalarApiReference();
}

app.MapScalarApiReference();

app.MapScalarApiReference("/api-docs");
app.MapScalarApiReference("/docs");

app.MapScalarApiReference(options =>
{
    options.WithTitle("My API");
});

app.MapScalarApiReference("/docs", options =>
{
    options.WithTitle("My API Documentation");
});

app.MapScalarApiReference((options, httpContext) =>
{
    var isAdmin = httpContext.User.IsInRole("Admin");
    options.WithTitle(isAdmin ? "Admin API" : "Public API");
});

// مسیر سفارشی با HttpContext
app.MapScalarApiReference("/docs", (options, httpContext) =>
{
    options.WithTitle($"API برای {httpContext.User.Identity?.Name}");
});

app.MapScalarApiReference(options =>
{
    options.WithTitle("E-Commerce API")
           .WithClassicLayout()             
           .ForceDarkMode()                
           .HideSearch()                    
           .ShowOperationId()              
           .ExpandAllTags()                 
           .SortTagsAlphabetically()        
           .SortOperationsByMethod()      
           .PreserveSchemaPropertyOrder()  
           .WithProxy("https://api-gateway.company.com")
           .AddServer("https://api.company.com", "Production")
           .AddServer("https://staging-api.company.com", "Staging");
});

• WithTitle: تعیین عنوان مستندات که در بالای صفحه و Title مرورگر نمایش داده می‌شود.
• WithClassicLayout: فعال‌کردن ظاهر کلاسیک Scalar که ساختاری مشابه Swagger UI دارد و منوی سمت چپ را نمایش می‌دهد.
• ForceDarkMode: اجبار UI به نمایش در حالت Dark Mode بدون توجه به تنظیمات سیستم یا مرورگر.
• HideSearch: مخفی کردن قابلیت جستجو در UI مستندات برای کاهش شلوغی و ساده‌تر شدن نمایش.
• ShowOperationId: نمایش مقدار operationId برای هر endpoint که برای Code Generation و Debugging بسیار کاربردی است.
• ExpandAllTags: باز بودن تمام گروه‌ها (Tags) به صورت پیش‌فرض هنگام لود صفحه تا همه Endpointها بدون کلیک‌کردن قابل مشاهده باشند.
• SortTagsAlphabetically: مرتب‌سازی دسته‌بندی‌های API بر اساس حروف الفبا جهت افزایش نظم و دسترسی بهتر.
• SortOperationsByMethod: مرتب‌سازی عملیات داخل هر دسته‌بندی بر اساس HTTP Method مانند: GET، POST، PUT، DELETE و غیره.
• PreserveSchemaPropertyOrder: حفظ ترتیب فیلدهای Schema دقیقاً مطابق ترتیب تعریف‌شده در کلاس‌های C# و جلوگیری از ترتیب‌دهی خودکار.
• WithProxy: ارسال درخواست‌های تستی UI از طریق API Gateway برای حل مشکل CORS و یکپارچگی ارتباطات.
• AddServer: افزودن محیط Production به لیست سرورها تا کاربر بتواند درخواست را مستقیماً به این محیط ارسال کند یا افزودن محیط Staging برای تست، QA و بررسی قبل از انتشار نهایی.

app.MapScalarApiReference(options =>
{
    options.WithOpenApiRoutePattern("/api-spec/{documentName}.json");
});

app.MapScalarApiReference(options =>
{
    options.WithOpenApiRoutePattern("https://api.example.com/openapi/{documentName}.json");
});

app.MapScalarApiReference(options => options.AddDocument("v1"));

app.MapScalarApiReference(options => options.AddDocument("v1", "Production API"));

app.MapScalarApiReference(options =>
{
    options.AddDocument("v1", "Production API", "api/v1/openapi.json")
           .AddDocument("v2-beta", "Beta API", "api/v2-beta/openapi.json", isDefault: true)
           .AddDocument("internal", "Internal API", "internal/openapi.json");
});

app.MapScalarApiReference(options => options
    .AddPreferredSecuritySchemes("ApiKey")
    .AddApiKeyAuthentication("ApiKey", apiKey =>
    {
        apiKey.Value = "sk-demo-key-12345";
    }));

app.MapScalarApiReference(options => options
    .AddPreferredSecuritySchemes("BearerAuth")
    .AddHttpAuthentication("BearerAuth", auth =>
    {
        auth.Token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    }));

app.MapScalarApiReference(options => options
    .AddPreferredSecuritySchemes("BasicAuth")
    .AddHttpAuthentication("BasicAuth", auth =>
    {
        auth.Username = "demo-user";
        auth.Password = "demo-password";
    }));

app.MapScalarApiReference(options => options
    .AddPreferredSecuritySchemes("OAuth2")
    .AddAuthorizationCodeFlow("OAuth2", flow =>
    {
        flow.ClientId = "scalar-demo-client";
        flow.ClientSecret = "scalar-demo-secret";
        flow.Pkce = Pkce.Sha256;
        flow.SelectedScopes = ["read", "write", "admin"];
    }));

app.MapScalarApiReference(options =>
{
    options.WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);
});

app.MapScalarApiReference(options =>
{
    options.WithBundleUrl("https://cdn.jsdelivr.net/npm/@scalar/api-reference");
});

app.MapScalarApiReference(options =>
{
    options.WithJavaScriptConfiguration("/scalar/config.js");
});

builder.Services.Configure<ScalarOptions>(options => options.Title = "My API");

app.MapScalarApiReference().AllowAnonymous();