在 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

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

相关推荐
csdn_aspnet8 天前
.NET 9 彻底改变了 API 文档:从 Swashbuckle(Swagger) 到 Scalar
.net9
csdn_aspnet9 天前
在 .NET 9.0 Web API 中实现 Scalar 接口文档及JWT集成
jwt·.net9·scalar
csdn_aspnet16 天前
Swagger 从 .NET 9 中删除:有哪些替代方案
swagger·openapi·.net9
csdn_aspnet17 天前
.NET 9 中 OpenAPI 替代 Swagger 文档生成
.net9
界面开发小八哥1 个月前
界面组件DevExpress WPF中文教程:Grid - 如何显示和隐藏列?
wpf·界面控件·devexpress·ui开发·.net9
界面开发小八哥1 个月前
DevExpress WPF中文教程:Grid - 如何创建未绑定列?
wpf·界面控件·devexpress·ui开发·.net9
慧都小妮子3 个月前
.NET 9微软新平台 + FastReport .NET:如何提升报告生成效率
microsoft·.net·报表控件·fastreport·.net9
IT规划师4 个月前
.NET9 - Swagger平替Scalar详解(四)
c#13·.net9·scalar