.NET 9中Scalar OpenAPI文档无法展示多API版本的问题求助

我有一个ASP.NET Core 9 Web API应用程序，.NET 9默认不再使用Swashbuckle，改用Microsoft OpenAPI文档和Scalar生成API文档。我已经在控制器中启用了API版本控制，所有版本的OpenAPI文档都已成功生成。

我创建了两个OpenAPI文档：v1.json和v2.json，均可通过默认路由/openapi/{documentName}.json访问。但Scalar UI仅能识别/openapi/v1.json中的端点，因为这是Scalar的默认配置。

我需要如何操作才能像SwaggerUI一样，在Scalar的单个页面中展示所有版本的文档？

解决方案 #

要让Scalar支持多版本API文档，需自定义Scalar的配置选项，显式添加所有版本的OpenAPI文档地址，替换默认的MapScalarApiReference()调用：

1. 修改Program.cs中的Scalar配置
   将原有的app.MapScalarApiReference()替换为带配置参数的重载，添加多版本文档条目：

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    
    // 自定义Scalar配置，添加多版本文档
    app.MapScalarApiReference(options =>
    {
        options.Documents.Add(new ScalarDocument
        {
            Title = "API V1",
            Url = "/openapi/v1.json"
        });
        options.Documents.Add(new ScalarDocument
        {
            Title = "API V2",
            Url = "/openapi/v2.json"
        });
    });
}

2. 确保安装Scalar.AspNetCore包
   如果尚未安装，执行以下命令添加NuGet包：

dotnet add package Scalar.AspNetCore

3. 保留API版本控制配置
   保持原有的AddApiVersioning和AddApiExplorer配置不变，它负责按版本生成正确的OpenAPI文档：

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(2, 0);
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("x-api-version"),
        new QueryStringApiVersionReader("api-version")
    );
})
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

重启应用后，访问Scalar UI默认地址/scalar，即可看到顶部的版本选择下拉菜单，切换不同版本查看对应API文档，实现和SwaggerUI一致的多版本展示效果。

内容的提问来源于stack exchange，提问作者Achyut Manvar