使用Scalar.AspNetCore来管理你的OpenApi

想做蜗牛的蝎 發表於 2025-10-17 17:28:00

使用Scalar.AspNetCore来管理你的OpenApi

一直觉得很好的一个组件，网上介绍少得可怜，没办法，只有自己爬官网了，又是对照git又是看doc文档，总算是玩明白了，现在完全抛弃那个谁谁谁了。因人喜好各取所长吧
先来官方参考地址：
https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/openapi/include-metadata?view=aspnetcore-9.0&tabs=minimal-apis
这是scalar的.net 集成文档地址
https://guides.scalar.com/scalar/scalar-api-references/integrations/net-aspnet-core/integration
github地址
https://github.com/scalar/scalar
先放个图，诱惑一下，集成了很多主题，还可以自定主题（留给前端去玩吧）
<img src="https://img2024.cnblogs.com/blog/43211/202510/43211-20251017160114922-1289434129.png" alt="01" width="965" height="482" loading="lazy">
 
一、简单使用
1.建立一个API项目，（最小，mvc都可）
2.引用包
 dotnet add package Scalar.AspNetCore （当前版本2.9.0）
<div> dotnet add package Microsoft.AspNetCore.OpenApi（当前版本10.0）</div>
3.添加引用
using Scalar.AspNetCore;
4.添加配置，在Program.cs中添加下面配置
<div class="cnblogs_code">
<pre>builder.Services.AddOpenApi();

if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.MapScalarApiReference();
}</pre>
</div>
现在运行一下，看看，localhost:xxxx/scalar
是不是看到列出漂亮的界面了？
二、基本配置
1.自定义路由
不想使用/salar，可以换成自己的地址
<div class="cnblogs_code">
<pre>app.MapScalarApiReference("/api-docs");
app.MapScalarApiReference("/docs");</pre>
</div>
2.多文当或版本控制
<div class="cnblogs_code">
<pre>// Chain multiple documents
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");
});</pre>
</div>
<pre>isDefault: true是默认打开的页面 3.自定义文档的默认调试语言</pre>
<div class="cnblogs_code">
<pre>app.MapScalarApiReference(options =>
{
options.WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);
});</pre>
</div>
<img src="https://img2024.cnblogs.com/blog/43211/202510/43211-20251017162848040-1986574236.png" alt="02" width="744" height="242" loading="lazy">
它对应右边窗口的语言，基本上都支持，java,php,rust,py,swift
三、高级配置
之前的老版本使用的硬编码option加配置，2.9.0以后，在界面右上角菜单栏上出现了一个编辑配置功能
<img src="https://img2024.cnblogs.com/blog/43211/202510/43211-20251017163326465-796338346.png" alt="03" width="346" height="612" loading="lazy">
根据自己的喜好，调试编辑完配置文件后，可以复制到文件中单独保存，真是太贴心了
<div class="cnblogs_code">
<pre>{
"title": "Aquxa API Documentation",
"slug": "aquxa-api-documentation",
"hideClientButton": true,
"servers": [
{
 "url": "http://localhost:5215",
 "description": "Development server"
}
],
"showSidebar": true,
"showToolbar": "localhost",//这里特别说明一下，编辑完后，不想出现这个菜单栏，就在这里可以关闭showToolbar: "never"
"operationTitleSource": "summary",
"theme": "solarized",//主题可以自己选，喜欢哪个选哪个
"_integration": "dotnet",
"persistAuth": false,
"telemetry": true,
"layout": "modern",
"isEditable": false,
"isLoading": false,
"hideModels": true,
"documentDownloadType": "both",
"hideTestRequestButton": false,
"hideSearch": false,
"showOperationId": false,
"hideDarkModeToggle": false,
"favicon": "favicon.svg",
"withDefaultFonts": true,
"defaultOpenAllTags": false,
"expandAllModelSections": true,
"expandAllResponses": true,
"orderSchemaPropertiesBy": "alpha",
"orderRequiredPropertiesFirst": true,
"url": "http://localhost:5215/openapi/v1.json"
}</pre>
</div>
<pre>PS：这里特别说明一下，编辑完后，不想出现这个菜单栏，就在这里可以关闭showToolbar: "never" 得到这个文件，保存到wwwroot/js/scalar-config.js，注意，一定要保存到能访问的静态目录里，并在program.cs添加静态目录的配置 <code class="t-editor__inline-code"></code></pre>
<div class="cnblogs_code">
<pre>app.UseStaticFiles(). //这个要放在scalar配置的前面，不然访问不到</pre>
</div>
添加配置文件加载
<div class="cnblogs_code">
<pre>.WithJavaScriptConfiguration("/js/scalar-config.js") </pre>
</div>
 
<img src="https://img2024.cnblogs.com/blog/43211/202510/43211-20251017164201407-1694509419.png" alt="04" loading="lazy">
这里费了好大的劲，查官方，看代码，因为官方文档还是老文档，只是简单的概括了一下。最后整出来了
四、文档的编辑
使用最重要的还是API文档编辑，其实它完全用的标准的OpenApi，只要参考这个表就可以完全配置了
<img src="https://img2024.cnblogs.com/blog/43211/202510/43211-20251017165047566-1432136520.png" alt="05" loading="lazy">
<div class="cnblogs_code">
<pre>
")]

// 为整个控制器添加标签
public class AdminController : ControllerBase
{

 public IActionResult ReloadCache()
 {
 // 模拟重新加载缓存的操作
 return Ok("Cache reloaded successfully");
 }


 public IActionResult GetStats()
 {
 return Ok(new { Users = 100, Requests = 1000 });
 }
}</pre>
</div>
下面说一下常用的特性
1.API分组
<div>
<div class="cnblogs_code">
<pre> </pre>
</div>
这个比较熟悉，它可以分组，分版本，当你分好版本后/，会在scalar中左上角可以选择，当然，你也可以把它做为组来用
<img src="https://img2024.cnblogs.com/blog/43211/202510/43211-20251017165845787-1124928420.png" alt="06" loading="lazy">
如果有不想显示的API也可以用来排除显示
<div class="cnblogs_code">
<pre>

public IActionResult PrivateEndpoint() {
return Ok("This is a private endpoint");
}</pre>
</div>
2.API分类
<div class="cnblogs_code">
<pre></pre>
</div>
分类的API，会归档在一起，方便查询，这样看起来没有那么乱了
<div class="cnblogs_code">
<pre>)]

public IResult Attributes()
{
return Results.Ok("Hello world!");
}</pre>
</div>
<img src="https://img2024.cnblogs.com/blog/43211/202510/43211-20251017170534464-553519957.png" alt="07" loading="lazy">
3.描述
<div class="cnblogs_code">
<pre>

public IResult Attributes()
{
return Results.Ok("Hello world!");
}</pre>
</div>
<img src="https://img2024.cnblogs.com/blog/43211/202510/43211-20251017170839444-1940993122.png" alt="08" loading="lazy">
4.过滤
不想显示的接口可以用
上面说的
<pre>来关闭 还有一个就是根目录，如果在配置文件中有MapGet，可以使用.ExcludeFromDescription();排除显示</pre>
<pre> </pre>
<div class="cnblogs_Highlighter">
<pre class="brush:csharp;gutter:true;"> // 默认打开首页
app.MapGet("/", () => "Hangfire 服务运行中。访问 /hangfire 查看仪表盘，访问 /docs 查看API文档").ExcludeFromDescription();
//可以使用.ExcludeFromDescription();排除显示
</pre>
</div>
　　
<pre> </pre>
更多编辑文档就看这里吧
https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/openapi/include-metadata?view=aspnetcore-9.0&tabs=controllers
五、认证授权
这里就使用自己的授权就可以，这里就偷懒找AI完成了。参考部分都有备注
<div class="cnblogs_code">
<pre>using Scalar.AspNetCore;
using Microsoft.AspNetCore.Authentication;
using Microsoft.Extensions.Options;
using System.Security.Claims;
using System.Text.Encodings.Web;
using Microsoft.AspNetCore.Mvc;
using MyWebApi; // 添加对WeatherForecast的引用

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
// 添加控制器服务
builder.Services.AddControllers();

// 添加身份验证服务
builder.Services.AddAuthentication("BasicAuthentication")
.AddScheme<AuthenticationSchemeOptions, BasicAuthenticationHandler>("BasicAuthentication", null);

// 添加授权服务
builder.Services.AddAuthorization(options =>
{
options.AddPolicy("ScalarAccess", policy => policy.RequireAuthenticatedUser());
});

// 配置服务器URL，避免端口冲突
builder.WebHost.UseUrls("http://localhost:5215");
var app = builder.Build();

// Configure static file middleware to serve the JavaScript config file
app.UseStaticFiles();

// 添加身份验证和授权中间件
app.UseAuthentication();
app.UseAuthorization();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
// Add Scalar for API management with JavaScript configuration and authorization
app.MapScalarApiReference("/scalar", options =>
{
 options.WithTitle("MyWebApi")
 .WithJavaScriptConfiguration("/js/scalar-config.js")
 .AddDocument("v1", "Aquxa API Documentation",isDefault: true)
 .AddDocument("v2", "Beta API");
})
.RequireAuthorization("ScalarAccess"); // 应用授权策略
}

// 添加控制器路由
app.MapControllers();

app.Run();

// Basic Authentication Handler
public class BasicAuthenticationHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
public BasicAuthenticationHandler(
 IOptionsMonitor<AuthenticationSchemeOptions> options,
 ILoggerFactory logger,
 UrlEncoder encoder)
 : base(options, logger, encoder)
{
}

protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
{
 // 检查是否有Authorization头
 if (!Request.Headers.ContainsKey("Authorization"))
 return AuthenticateResult.NoResult();

 try
 {
 // 解析Basic认证头
 var authHeader = Request.Headers["Authorization"].ToString();
 if (!authHeader.StartsWith("Basic "))
 return AuthenticateResult.NoResult();

 var encodedCredentials = authHeader.Substring("Basic ".Length).Trim();
 var decodedCredentials = System.Text.Encoding.UTF8.GetString(Convert.FromBase64String(encodedCredentials));
 var credentials = decodedCredentials.Split(':', 2);

 var username = credentials[0];
 var password = credentials[1];

 // 验证用户名和密码（这里使用硬编码，实际应用中应从配置或数据库获取）
 if (username == "admin" && password == "password123")
 {
 var claims = new[] { new Claim(ClaimTypes.Name, username) };
 var identity = new ClaimsIdentity(claims, Scheme.Name);
 var principal = new ClaimsPrincipal(identity);
 var ticket = new AuthenticationTicket(principal, Scheme.Name);

 return AuthenticateResult.Success(ticket);
 }

 return AuthenticateResult.Fail("Invalid username or password");
 }
 catch
 {
 return AuthenticateResult.Fail("Invalid Authorization Header");
 }
}

protected override async Task HandleChallengeAsync(AuthenticationProperties properties)
{
 // 发送WWW-Authenticate头以触发浏览器的认证对话框
 Response.Headers["WWW-Authenticate"] = "Basic realm=\"Scalar API Documentation\"";
 await base.HandleChallengeAsync(properties);
}
}</pre>
</div>
 <img src="https://img2024.cnblogs.com/blog/43211/202510/43211-20251017172606610-102964762.png" alt="09" loading="lazy">
 
</div>
<pre></pre> 
来源：https://www.cnblogs.com/wangbin5542/p/19148516

頁: [1]

琼殿技术论坛's Archiver

使用Scalar.AspNetCore来管理你的OpenApi