ASP.NET Core 6.0 Minimal API如何配置Swagger标签实现接口逻辑分组

云上老周

2026-10-2

问题原因

直接将[SwaggerOperation]特性加在委托方法上不会生效，是因为Minimal API的端点元数据收集逻辑和传统Controller不同，委托上标注的特性默认不会被Swagger扫描识别。

标准实现方案

方案1：使用官方原生`WithTags`扩展方法（最推荐）

ASP.NET Core Minimal API 原生提供了WithTags()扩展方法专门用于配置接口分组标签，无需额外依赖或配置，Swagger原生支持识别：

// ToDo分组接口
app.MapGet("/todo", () => "Hello world")
   .WithTags("ToDo");
app.MapPost("/todo", () => "Hello world")
   .WithTags("ToDo");

// Projects分组接口
app.MapGet("/projects", () => "Hello world")
   .WithTags("Projects");
app.MapPost("/projects", () => "Hello world")
   .WithTags("Projects");

该方案效果和传统Controller模式下的标签分组完全一致，还支持给单个接口配置多个标签，只需在WithTags中传入多个字符串参数即可。

方案2：手动注入`SwaggerOperation`元数据

如果你需要使用SwaggerOperationAttribute的其他配置（比如接口说明、操作ID等），可以通过WithMetadata()方法手动将特性注入到端点元数据中：

app.MapGet("/todo", () => "Hello world")
   .WithMetadata(new SwaggerOperationAttribute
   {
       Tags = new[] { "ToDo" },
       Summary = "获取ToDo列表",
       Description = "返回所有ToDo数据"
   });