如何在ASP.NET Core 9中用OpenAPI和Scalar分组API控制器

完全可以实现端点分组，核心是通过给控制器添加标签，让OpenAPI生成对应的分组元数据，Scalar会自动读取这些元数据并在UI中按组展示。具体步骤如下：

1. 给控制器添加分组标签 #

在需要归为同一组的控制器上添加[Tags]属性，指定分组名称：

// User组 - 认证控制器
[ApiController]
[Tags("User")]
[Route("api/auth")]
public class AuthController : ControllerBase
{
    // 登录、注册等端点逻辑
}

// User组 - 个人资料控制器
[ApiController]
[Tags("User")]
[Route("api/profile")]
public class ProfileController : ControllerBase
{
    // 修改资料、获取资料等端点逻辑
}

// Order组 - 订单控制器
[ApiController]
[Tags("Order")]
[Route("api/orders")]
public class OrdersController : ControllerBase
{
    // 创建订单、查询订单等端点逻辑
}

// Order组 - 支付控制器
[ApiController]
[Tags("Order")]
[Route("api/payments")]
public class PaymentsController : ControllerBase
{
    // 创建支付、查询支付状态等端点逻辑
}

2. 确保OpenAPI正确识别分组标签 #

ASP.NET Core 9的AddEndpointsApiExplorer和AddOpenApi默认会自动读取控制器上的[Tags]属性，将其转换为OpenAPI文档中的tags字段。如果需要自定义文档信息，可以在配置OpenAPI时补充：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();

builder.Services.AddOpenApi(options =>
{
    options.AddDocument("v1", doc =>
    {
        doc.Title = "业务API";
        doc.Version = "v1";
        // 无需额外配置标签，控制器的[Tags]会自动同步到OpenAPI文档
    });
});

var app = builder.Build();

// 启用Scalar API文档UI
app.MapScalarApiReference();

app.MapControllers();
app.Run();

3. Scalar自动展示分组 #

Scalar会直接解析OpenAPI文档中的tags信息，在UI界面中将同一标签的端点自动归为一组，你可以在Scalar的页面中看到User、Order等分组，点击分组即可查看对应控制器的所有端点。

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