在 ASP .NET Core 9.0 中使用 Scalar 创建漂亮的 API 文档

示例代码：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 

如果您喜欢此文章，请收藏、点赞、评论，谢谢，祝您快乐每一天。