ASP.NET Core中如何在Swagger UI添加第二个OpenAPI文档定义？

你已经通过ApiExplorerSettingsAttribute的GroupName属性生成了独立的OpenAPI文档（可通过/swagger/ABC_v1/swagger.json访问），但Swagger UI的定义下拉菜单里看不到该文档，核心原因是Swagger UI默认不会自动识别自定义分组的文档，需要手动配置加载逻辑。

具体修复步骤（以.NET 5+/6+/7+为例） #

1. 配置Swagger生成器，注册自定义分组文档
   在Program.cs中，为你的分组添加Swagger文档定义：

builder.Services.AddSwaggerGen(c =>
{
    // 文档名称必须和控制器上的GroupName完全一致
    c.SwaggerDoc("ABC_v1", new OpenApiInfo 
    {
        Title = "ABC API v1",
        Version = "v1",
        Description = "ABC业务模块的API接口文档"
    });
});

注意：这里的文档名称要和控制器ApiExplorerSettings(GroupName = "ABCv1")里的名称严格匹配——你当前的访问路径是ABC_v1，但控制器上是ABCv1，这大概率是名称不匹配导致的问题，需要统一两者的命名（比如都改成ABC_v1或者ABCv1）。

2. 配置Swagger UI，加载自定义分组文档
   同样在Program.cs中，配置Swagger UI加载你注册的分组文档：

app.UseSwaggerUI(c =>
{
    // 添加上一步注册的文档，第一个参数是swagger.json的访问路径，第二个是下拉菜单显示的名称
    c.SwaggerEndpoint("/swagger/ABC_v1/swagger.json", "ABC API v1");
    
    // 保持Swagger UI的默认路由前缀
    c.RoutePrefix = "swagger";
});

关键注意事项 #

• 分组名称必须全局一致：控制器的GroupName、SwaggerDoc的文档名称、SwaggerEndpoint里的路径名称三者必须完全相同，包括大小写、下划线等符号。
• 确保UseSwagger中间件已正确添加：在UseSwaggerUI之前，必须先调用app.UseSwagger()，否则Swagger JSON文件无法被访问。

如果是ASP.NET Core 2.x或更早版本，配置逻辑完全一致，只是需要把代码放在Startup.cs的ConfigureServices和Configure方法中。

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