Swagger生成冲突：同路由同名不同版本API无法正常展示如何解决？

前置依赖 #

首先确保项目已安装以下NuGet包：

• Microsoft.AspNetCore.Mvc.Versioning
• Swashbuckle.AspNetCore.Swagger
• Swashbuckle.AspNetCore.SwaggerUI

步骤1：配置API版本控制服务 #

在Program.cs（.NET 6+）或Startup.cs的ConfigureServices方法中添加API版本控制配置，指定版本读取规则（因为路由中不包含版本，可选择从请求头或查询参数读取版本号）：

builder.Services.AddApiVersioning(options =>
{
    // 未指定版本时使用默认版本
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    // 响应头返回支持的API版本
    options.ReportApiVersions = true;
    // 配置版本读取方式，可二选一或同时支持
    // 方式1：从请求头读取版本，例如Header key为api-version
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
    // 方式2：从查询参数读取版本，例如查询参数为api-version
    // options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});

步骤2：配置Swagger多版本生成规则 #

在AddSwaggerGen配置中添加多版本文档定义，同时添加冲突解决规则和自定义操作过滤器，区分同路由不同版本的接口：

builder.Services.AddSwaggerGen(options =>
{
    // 为每个API版本定义Swagger文档
    options.SwaggerDoc("V1", new OpenApiInfo { Title = "API V1", Version = "V1" });
    options.SwaggerDoc("V2", new OpenApiInfo { Title = "API V2", Version = "V2" });
    
    // 核心：解决同路由接口的冲突问题
    options.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
    
    // 添加自定义操作过滤器，给同路由的不同版本接口添加版本标识，避免重复判定
    options.OperationFilter<SwaggerVersionOperationFilter>();
});

步骤3：实现自定义操作过滤器 #

新建SwaggerVersionOperationFilter类，为每个接口添加版本后缀，区分同路由的不同版本操作：

public class SwaggerVersionOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var apiVersion = context.ApiDescription.GetApiVersion();
        if (apiVersion == null) return;
        
        // 给OperationId添加版本后缀，避免Swagger判定为重复操作
        operation.OperationId += $"_{apiVersion}";
        // 可选：在接口描述中标注版本号，更易识别
        operation.Summary = $"[API {apiVersion}] {operation.Summary}";
    }
}

步骤4：配置SwaggerUI多版本访问 #

在中间件配置部分添加SwaggerUI的多版本终结点配置：

app.UseSwagger();
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/V1/swagger.json", "API V1");
    options.SwaggerEndpoint("/swagger/V2/swagger.json", "API V2");
});

配置完成后，Swagger会分别生成V1和V2两个版本的swagger.json文档，两个同路由不同版本的接口会分别收录到对应版本的文档中，不需要修改原有路由配置。

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