示例代碼：https://download.csdn.net/download/hefeng_aspnet/90407900?
????????Scalar 是一款可幫助我們為 API 創建精美文檔的工具。與感覺有些過時的默認 Swagger 文檔不同，Scalar 為 API 文檔提供了全新而現代的 UI。其簡潔的設計讓開發人員可以輕松找到測試所需的 API。
????????在本文中，我們將探討如何在 ASP.NET Core Web API 中使用 Scalar 進行 API 文檔編寫以替換默認的 Swagger UI。
安裝 Scalar
打開 NuGet 包管理器，搜索并安裝Scalar.AspNetCore包：
配置Scalar
打開Program.cs文件并替換默認的 swagger 配置：
From this：
if (app.Environment.IsDevelopment())
{
? ? app.UseSwagger();
? ? app.UseSwaggerUI();
}
To this：
app.UseSwagger(opt =>
{
? ? opt.RouteTemplate = "openapi/{documentName}.json";
});
app.MapScalarApiReference(opt =>
{
? ? opt.Title = "Scalar Example";
? ? opt.Theme = ScalarTheme.Mars;
? ? opt.DefaultHttpClient = new(ScalarTarget.Http, ScalarClient.Http11);
});
持有者認證
我們還可以向 Scalar 文檔添加 Bearer 身份驗證標頭。只需將builder.Services.AddSwaggerGen();配置替換為以下內容：
builder.Services.AddSwaggerGen(opt =>?
{
? ? opt.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
? ? {
? ? ? ? BearerFormat = "JWT",
? ? ? ? Description = "JWT Authorization header using the Bearer scheme.",
? ? ? ? Name = "Authorization",
? ? ? ? In = ParameterLocation.Header,
? ? ? ? Type = SecuritySchemeType.Http,
? ? ? ? Scheme = "Bearer"
? ? });
? ? opt.AddSecurityRequirement(new OpenApiSecurityRequirement
? ? ? ? ? ? {
? ? ? ? ? ? ? ? {
? ? ? ? ? ? ? ? ? ? new OpenApiSecurityScheme
? ? ? ? ? ? ? ? ? ? {
? ? ? ? ? ? ? ? ? ? ? ? Reference = new OpenApiReference
? ? ? ? ? ? ? ? ? ? ? ? {
? ? ? ? ? ? ? ? ? ? ? ? ? ? Id = "Bearer",
? ? ? ? ? ? ? ? ? ? ? ? ? ? Type = ReferenceType.SecurityScheme
? ? ? ? ? ? ? ? ? ? ? ? }
? ? ? ? ? ? ? ? ? ? },
? ? ? ? ? ? ? ? ? ? Array.Empty<string>()
? ? ? ? ? ? ? ? }
? ? ? ? ? ? });
});
這是完整的Program.cs文件：
using Microsoft.OpenApi.Models;
using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(opt =>?
{
? ? opt.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
? ? {
? ? ? ? BearerFormat = "JWT",
? ? ? ? Description = "JWT Authorization header using the Bearer scheme.",
? ? ? ? Name = "Authorization",
? ? ? ? In = ParameterLocation.Header,
? ? ? ? Type = SecuritySchemeType.Http,
? ? ? ? Scheme = "Bearer"
? ? });
? ? opt.AddSecurityRequirement(new OpenApiSecurityRequirement
? ? ? ? ? ? {
? ? ? ? ? ? ? ? {
? ? ? ? ? ? ? ? ? ? new OpenApiSecurityScheme
? ? ? ? ? ? ? ? ? ? {
? ? ? ? ? ? ? ? ? ? ? ? Reference = new OpenApiReference
? ? ? ? ? ? ? ? ? ? ? ? {
? ? ? ? ? ? ? ? ? ? ? ? ? ? Id = "Bearer",
? ? ? ? ? ? ? ? ? ? ? ? ? ? Type = ReferenceType.SecurityScheme
? ? ? ? ? ? ? ? ? ? ? ? }
? ? ? ? ? ? ? ? ? ? },
? ? ? ? ? ? ? ? ? ? Array.Empty<string>()
? ? ? ? ? ? ? ? }
? ? ? ? ? ? });
});
var app = builder.Build();
app.UseSwagger(opt =>
{
? ? opt.RouteTemplate = "openapi/{documentName}.json";
});
app.MapScalarApiReference(opt =>
{
? ? opt.Title = "Scalar Example";
? ? opt.Theme = ScalarTheme.Mars;
? ? opt.DefaultHttpClient = new(ScalarTarget.Http, ScalarClient.Http11);
});
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();
啟動設置
為了讓 Scalar 在運行應用程序時自動打開，我們需要調整LaunchSettings.json文件。我們可以在Properties文件夾中找到此文件：
打開LaunchSettings.json文件并將“launchUrl”: “swagger”配置更改為“launchUrl”: “scalar/v1”：
{
? "$schema": "http://json.schemastore.org/launchsettings.json",
? "iisSettings": {
? ? "windowsAuthentication": false,
? ? "anonymousAuthentication": true,
? ? "iisExpress": {
? ? ? "applicationUrl": "http://localhost:39471",
? ? ? "sslPort": 44375
? ? }
? },
? "profiles": {
? ? "http": {
? ? ? "commandName": "Project",
? ? ? "dotnetRunMessages": true,
? ? ? "launchBrowser": true,
? ? ? "launchUrl": "scalar/v1",
? ? ? "applicationUrl": "http://localhost:5290",
? ? ? "environmentVariables": {
? ? ? ? "ASPNETCORE_ENVIRONMENT": "Development"
? ? ? }
? ? },
? ? "https": {
? ? ? "commandName": "Project",
? ? ? "dotnetRunMessages": true,
? ? ? "launchBrowser": true,
? ? ? "launchUrl": "scalar/v1",
? ? ? "applicationUrl": "https://localhost:7242;http://localhost:5290",
? ? ? "environmentVariables": {
? ? ? ? "ASPNETCORE_ENVIRONMENT": "Development"
? ? ? }
? ? },
? ? "IIS Express": {
? ? ? "commandName": "IISExpress",
? ? ? "launchBrowser": true,
? ? ? "launchUrl": "scalar/v1",
? ? ? "environmentVariables": {
? ? ? ? "ASPNETCORE_ENVIRONMENT": "Development"
? ? ? }
? ? }
? }
}?
運行應用程序
現在讓我們運行該應用程序：
測試要求
我們的 API 文檔現在看起來很棒！
使用 Scalar 編寫 API 文檔有很多好處，可以簡化開發人員的體驗。設計非常漂亮。側面菜單導航讓我們無需滾動即可快速找到各個部分，而測試請求功能讓我們可以直接從文檔中測試 API 端點。
完整的源代碼可以在這里找到：https://download.csdn.net/download/hefeng_aspnet/90407900?
如果您喜歡此文章，請收藏、點贊、評論，謝謝，祝您快樂每一天。
)
