能否在Minimal API中为Swagger添加独立分组章节？

可以实现，以下是几种实用的方式来给Minimal API的Swagger文档添加分组，达到和传统Controllers一致的效果：

1. 单个端点手动指定标签 #

在定义每个端点时，通过WithTags()方法给端点打上相同的标签，Swagger会自动将同一标签的端点归为一个分组章节：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

// 用户管理分组
app.MapGet("/api/users", () => Results.Ok(new List<string> { "张三", "李四" }))
   .WithTags("用户管理")
   .WithSummary("获取用户列表");

app.MapPost("/api/users", (string username) => Results.Created($"/api/users/{username}", username))
   .WithTags("用户管理")
   .WithSummary("创建新用户");

// 订单管理分组
app.MapGet("/api/orders", () => Results.Ok(new List<int> { 1001, 1002 }))
   .WithTags("订单管理")
   .WithSummary("获取订单列表");

app.Run();

2. 通过路由组批量设置标签 #

如果一组端点共享相同的路由前缀，可以用MapGroup()创建路由组，然后给整个组统一添加标签，避免重复编写WithTags()：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

// 创建用户管理路由组并统一设置标签
var userGroup = app.MapGroup("/api/users").WithTags("用户管理");
userGroup.MapGet("/", () => Results.Ok(new List<string> { "张三", "李四" }))
         .WithSummary("获取用户列表");
userGroup.MapPost("/", (string username) => Results.Created($"/api/users/{username}", username))
         .WithSummary("创建新用户");

// 创建订单管理路由组并统一设置标签
var orderGroup = app.MapGroup("/api/orders").WithTags("订单管理");
orderGroup.MapGet("/", () => Results.Ok(new List<int> { 1001, 1002 }))
          .WithSummary("获取订单列表");

app.Run();

3. 自定义分组规则（进阶） #

如果需要更灵活的分组逻辑（比如根据路由前缀自动分组），可以在AddSwaggerGen()中配置TagActionsBy来自定义分组规则，还能给分组添加描述信息：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    // 自定义标签分配规则
    options.TagActionsBy(api =>
    {
        if (api.RelativePath?.StartsWith("api/users") == true)
        {
            return new[] { "用户管理" };
        }
        else if (api.RelativePath?.StartsWith("api/orders") == true)
        {
            return new[] { "订单管理" };
        }
        // 未匹配的端点归到默认分组
        return new[] { "默认分组" };
    });

    // 给每个分组添加描述
    options.TagDescriptions.Add("用户管理", new OpenApiTagDescription 
    { 
        Description = "负责用户的创建、查询等核心操作" 
    });
    options.TagDescriptions.Add("订单管理", new OpenApiTagDescription 
    { 
        Description = "处理订单的查询、状态更新等业务" 
    });

    options.SwaggerDoc("v1", new OpenApiInfo { Title = "Minimal API 分组示例", Version = "v1" });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.MapGet("/api/users", () => Results.Ok(new List<string> { "张三", "李四" }));
app.MapPost("/api/users", (string username) => Results.Created($"/api/users/{username}", username));
app.MapGet("/api/orders", () => Results.Ok(new List<int> { 1001, 1002 }));

app.Run();

以上方式都能让Swagger UI生成和Controllers一样的独立分组章节，你可以根据自己的项目需求选择合适的实现方式。

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