NSwag中Minimal API分组配置的正确方式

在使用NSwag为ASP.NET Core Minimal API生成OpenAPI/Swagger文档时，许多开发者会遇到API端点分组显示不符合预期的问题。本文将详细介绍如何正确配置Minimal API的分组，使其在Swagger UI中按预期显示。

常见错误配置

开发者通常会尝试使用WithGroupName()方法来分组API端点，例如：

var group = app.MapGroup("jobs");
group = group.WithGroupName("MyJob");
group.MapGet("MyJob",...).WithGroupName("MyJob");

然而，这种配置方式在NSwag生成的Swagger UI中往往无法实现预期的分组效果，所有端点仍然会显示在默认分组中。

正确配置方法

实际上，NSwag主要依赖WithTags()方法而非WithGroupName()来实现API分组。正确的配置方式如下：

var group = app.MapGroup("jobs")
    .WithTags("MyJob");

group.MapGet("MyJob",...);
group.MapPost("MyJob",...);
group.MapDelete("MyJob",...);

app.MapGet("/jobs/TestJob", ...).WithTags("TestJob");
app.MapPost("/jobs/TestJob",...).WithTags("TestJob");

分组原理

1. 标签(Tags)的作用：在OpenAPI规范中，标签(Tags)是主要的API分组机制。NSwag会将这些标签转换为Swagger UI中的分组。

2. 层级关系：使用MapGroup创建的路由组可以统一设置标签，组内所有端点会自动继承这个标签。

3. 单独端点配置：对于不在组内的独立端点，可以直接使用WithTags()方法为其指定分组标签。

最佳实践

1. 对于相关功能集的API端点，优先使用MapGroup进行统一分组管理

2. 在组级别使用WithTags()设置分组名称，避免在每个端点重复设置

3. 确保分组名称具有明确的业务含义，便于API使用者理解

4. 对于跨多个分组的端点，可以传递多个标签名称：

   .WithTags("Group1", "Group2")
   

通过正确使用WithTags()方法，开发者可以轻松实现Minimal API在Swagger UI中的清晰分组展示，提升API文档的可读性和易用性。