.NET 8中如何用Swashbuckle自定义swagger.json文件名并拆分文档

要实现同一版本号下拆分Swagger文档，同时自定义JSON文件名，核心是通过多文档配置+自定义路由模板来实现，具体步骤如下：

1. 配置多Swagger文档 #

在AddSwaggerGen中注册多个文档，给每个文档设置相同的Version，但不同的Name（这个Name会对应到后续的文件名部分）：

services.AddSwaggerGen(c =>
{
    // 注册3个同版本、不同名称的文档
    c.SwaggerDoc("file1", new OpenApiInfo { Title = "File1 API V1", Version = "v1" });
    c.SwaggerDoc("file2", new OpenApiInfo { Title = "File2 API V1", Version = "v1" });
    c.SwaggerDoc("file3", new OpenApiInfo { Title = "File3 API V1", Version = "v1" });

    // 添加文档过滤器，用于筛选每个文档对应的API
    c.DocumentFilter<GroupDocumentFilter>();
});

2. 实现文档筛选过滤器 #

通过IDocumentFilter接口，根据API的特性或路由规则，将不同的API分配到对应的Swagger文档中。这里推荐用自定义特性标记的方式，更灵活：

自定义分组特性 #

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
public class SwaggerGroupAttribute : Attribute
{
    public string GroupName { get; }
    public SwaggerGroupAttribute(string groupName) => GroupName = groupName;
}

在控制器/方法上标记分组 #

// 给File1控制器标记属于file1分组
[ApiController]
[Route("api/file1")]
[SwaggerGroup("file1")]
public class File1Controller : ControllerBase
{
    // 控制器内的接口都会被分配到file1文档
}

// 同理标记File2、File3控制器
[SwaggerGroup("file2")]
public class File2Controller : ControllerBase { ... }

实现筛选逻辑的过滤器 #

public class GroupDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 当前处理的文档名称（对应SwaggerDoc的Name）
        var targetGroup = swaggerDoc.Name;
        var filteredPaths = new OpenApiPaths();

        foreach (var (path, pathItem) in swaggerDoc.Paths)
        {
            // 检查当前路径对应的API是否属于目标分组
            bool isInGroup = pathItem.Operations.Values.Any(op =>
                context.ApiDescriptions.FirstOrDefault(d => d.RelativePath == path)?.ActionDescriptor.EndpointMetadata
                    .Any(m => m is SwaggerGroupAttribute attr && attr.GroupName == targetGroup) ?? false);

            if (isInGroup)
            {
                filteredPaths.Add(path, pathItem);
            }
        }

        // 替换为筛选后的路径集合
        swaggerDoc.Paths = filteredPaths;
    }
}

3. 配置Swagger中间件的自定义路由 #

修改UseSwagger的路由模板，将文档名称嵌入到JSON文件名中，这样就能生成你需要的swagger-file1.json这类文件名：

app.UseSwagger(s =>
{
    s.SerializeAsV2 = true;
    // 自定义路由模板：{documentName}会替换为SwaggerDoc的Name（file1/file2/file3）
    s.RouteTemplate = "swagger/v1/swagger-{documentName}.json";
})
.UseSwaggerUI(c =>
{
    // 指向生成的自定义端点
    c.SwaggerEndpoint("/swagger/v1/swagger-file1.json", "File1 API V1");
    c.SwaggerEndpoint("/swagger/v1/swagger-file2.json", "File2 API V1");
    c.SwaggerEndpoint("/swagger/v1/swagger-file3.json", "File3 API V1");
});

这样配置完成后，启动项目就能在SwaggerUI中切换查看三个同版本的独立API文档，对应的JSON文件也会以你指定的文件名存在。

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