.NET 中使用Swagger 实现 API 分组管理
最终效果图
一.Swagger Api分组实现步骤：
- 在Program.cs 中配置 Swagger,并为每个分组设置对应的文档标题和版本号以及描述
builder.Services.AddSwaggerGen(options =>
{options.SwaggerDoc("v2", new OpenApiInfo{Version = "v2",Title = " WebApi",Description = "Api Services"});options.SwaggerDoc("v3", new OpenApiInfo{Version = "v3",Title = "WebApi",Description = "Api Services"});// 根据 GroupName 匹配文档版本options.DocInclusionPredicate((docName, apiDesc) =>{return apiDesc.GroupName == docName;});
});
- 启用 Swagger UI,并为每个版本指定一个文档端点
app.UseSwagger();
app.UseSwaggerUI(s =>
{s.SwaggerEndpoint("/swagger/v2/swagger.json", "WebApi v2");s.SwaggerEndpoint("/swagger/v3/swagger.json", "WebApi v3");
}
- 以上配置完成后，在控制器(Controller)上方添加 [ApiExplorerSettings] 特性或者添加在操作方法上方，并指定 GroupName即分组名称。例如，添加在控制器上：
- 最后访问 Swagger UI，你会看到两个文档选项：“WebApi v2” 和 “WebApi v3”。心腹每个分组文档中包含对应的 API
(以上使用.net 8配置)
二.API 文档中功能分组
使用 [Tags] 特性，可以实现将各个不同模块控制器的所有方法集中展示在Tage 指定的分组名称中
例如：没有使用Tage 特性前，这是2个不同控制器的方法
使用Tage 特性后,不同控制器的方法集中展示在Tage 指定的分组名称中。(注：2个控制器都需要同时配置Tags(“测试合并”))
Tage 特性在控制器配置显示如下:
说明: 只需要在 Program.cs 中正常配置 Swagger， [Tags] 特性无需额外配置，因为 [Tags] 特性会自动被 Swagger 识别的；
方法名后边显示的中文名称注释配置：
- 在控制器中的方法名上方添该特性 EndpointSummary(“测试”)
- 需要引入 Microsoft.AspNetCore.Http 包