在日常开发 webapi 时，我们往往会集成 swagger doc 进行 api 的文档呈现，当api数量比较多的时候就会导致 swagger ui 上的 api 因为数量太多而显得杂乱，今天教大家如何利用 GroupName 属性来对 api 的 Controller 进行分组，然后利用 swagger ui 上的 Select a definition 切换功能进行多组 Controller 的切换。
首先进行swagger注册
#region 注册 Swagger builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, SwaggerConfigureOptions>(); builder.Services.AddSwaggerGen(options => { options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{typeof(Program).Assembly.GetName().Name}.xml"), true); var modelPrefix = Assembly.GetEntryAssembly()?.GetName().Name + ".Models."; options.SchemaGeneratorOptions = new SchemaGeneratorOptions { SchemaIdSelector = type => type.ToString()[(type.ToString().IndexOf("Models.") + 7)..].Replace(modelPrefix, "").Replace("`1", "").Replace("+", ".") }; }); #endregion
然后启用 swagger
#region 启用 Swagger //启用中间件服务生成Swagger作为JSON端点 app.UseSwagger(); //启用中间件服务对swagger-ui，指定Swagger JSON端点 app.UseSwaggerUI(options => { var apiDescriptionGroups = app.Services.GetRequiredService<IApiDescriptionGroupCollectionProvider>().ApiDescriptionGroups.Items; foreach (var description in apiDescriptionGroups) { options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName); } }); #endregion
这里用到了一个自定义的 Swagger Doc 生成配置
public class SwaggerConfigureOptions : IConfigureOptions<SwaggerGenOptions> { private readonly IApiDescriptionGroupCollectionProvider provider; public SwaggerConfigureOptions(IApiDescriptionGroupCollectionProvider provider) => this.provider = provider; public void Configure(SwaggerGenOptions options) { foreach (var description in provider.ApiDescriptionGroups.Items) { options.SwaggerDoc(description.GroupName, null); } } }
这个方法的主要作用就是从 ApiDescriptionGroups 进行循环依次添加多个 Swagger Doc
然后关于本文目的的 swagger 配置就完成了。接下来就是对控制器进行分组标记的操作了。
关于对 Controller 进行 GroupName 分组，这里需要用到 ApiExplorerSettings 属性来标记 GroupName，并且同时修改 Route 信息，添加前缀，示例如下
/// <summary> /// 系统访问授权模块 /// </summary> [ApiExplorerSettings(GroupName = "Basic")] [Route("Basic/[controller]")] [ApiController] public class AuthorizeController : ControllerBase { }
这样就将 AuthorizeController 分到了 Basic 组，在 swagger ui 网页呈现如下
我们可以按照控制器的功能属性或者业务属性，将多个控制器分配到一个 Group。
上面讲的方法需要对所有的控制器进行添加 [ApiExplorerSettings(GroupName = "xxxxx")] 属性，下面顺便介绍一下如何通过文件的归类对 控制器进行批量添加 GroupName
我们可以调整我们的控制器存放为文件夹，将同一个组的控制器放在一个文件夹中，示例如下图
调整存放路径之后，利用 vs 的 同步命名空间功能，选中项目，直接右击 同步命名空间，就可以把所有控制器的命名空间都调整过来，命名空间的最后一节其实就是我们文件夹的名称，也就是我们的 GroupName，如下：
然后我们可以利用 IControllerModelConvention 在项目启动时获取控制器命名空间的最后一节的值，将他赋值到控制器的 [ApiExplorerSettings(GroupName = "xxxxx")] GroupName 属性，代码如下
public class GroupNameConvention : IControllerModelConvention { public void Apply(ControllerModel controller) { var controllerNamespace = controller.ControllerType.Namespace; var groupName = controllerNamespace!.Split('.').LastOrDefault(); controller.ApiExplorer.GroupName = groupName; } }
然后只要在项目启动时注入这个方法即可
builder.Services.AddMvc(options => { options.Conventions.Add(new GroupNameConvention()); });
这样就完成了对 控制器 GroupName 的批量赋值，不过如果想要保持路由前缀和 GroupName 一致的话，还是需要自己手动的调整一下 控制器的路由前缀。
