ASP.NET Core多版本API操作ID冲突：如何将版本纳入WithName？

完全可以将API版本纳入WithName的命名逻辑中，以此解决跨版本端点的操作ID重复冲突问题，以下是几种实用的实现方式：

1. 给版本路由组统一添加版本前缀 #

利用路由组的自定义约定，自动为组内所有端点的名称拼接API版本标识，适配你已有的MapGroup版本化配置：

var apiVersionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1, 0))
    .HasApiVersion(new ApiVersion(2, 0))
    .Build();

RouteGroupBuilder versionedGroup = app.MapGroup("api/v{apiVersion:apiVersion}")
    .WithApiVersionSet(apiVersionSet)
    .Add(endpointBuilder =>
    {
        endpointBuilder.Add(endpoint =>
        {
            if (endpoint.Metadata.GetMetadata<ApiVersionMetadata>() is { } versionMetadata)
            {
                // 获取当前端点绑定的API版本
                var targetVersion = versionMetadata.DeclaredApiVersions.FirstOrDefault() 
                    ?? versionMetadata.ImplementedApiVersions.FirstOrDefault() 
                    ?? new ApiVersion(1, 0);
                // 给端点名称添加版本前缀
                endpoint.DisplayName = $"v{targetVersion}_{endpoint.DisplayName}";
                // 最小API中OperationId默认同步DisplayName，无需额外设置
            }
        });
    });

// 跨版本端点：会自动生成v1_CommonEndpoint、v2_CommonEndpoint等命名
versionedGroup.MapGet("/common", () => "Common cross-version endpoint")
    .WithName("CommonEndpoint");

// 特定版本端点：生成v1_V1OnlyEndpoint
versionedGroup.MapGet("/v1-only", () => "V1 exclusive endpoint")
    .HasApiVersion(new ApiVersion(1, 0))
    .WithName("V1OnlyEndpoint");

2. 单个端点手动指定带版本的名称 #

如果需要更精细的控制，可以直接在WithName中手动拼接版本号，比如针对不同版本组单独配置：

var apiVersionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1, 0))
    .HasApiVersion(new ApiVersion(2, 0))
    .Build();

// V1专属路由组
var v1Group = app.MapGroup("api/v1")
    .WithApiVersionSet(apiVersionSet)
    .HasApiVersion(new ApiVersion(1, 0));

v1Group.MapGet("/common", () => "Common endpoint for V1")
    .WithName("v1_CommonEndpoint");

// V2专属路由组
var v2Group = app.MapGroup("api/v2")
    .WithApiVersionSet(apiVersionSet)
    .HasApiVersion(new ApiVersion(2, 0));

v2Group.MapGet("/common", () => "Common endpoint for V2")
    .WithName("v2_CommonEndpoint");

3. 封装扩展方法简化版本化命名 #

创建自定义扩展方法，把版本化命名逻辑封装起来，复用更方便：

public static class VersionedEndpointExtensions
{
    public static TBuilder WithVersionedName<TBuilder>(this TBuilder builder, string baseName) 
        where TBuilder : IEndpointConventionBuilder
    {
        builder.Add(endpoint =>
        {
            if (endpoint.Metadata.GetMetadata<ApiVersionMetadata>() is { } versionMetadata)
            {
                var apiVersion = versionMetadata.DeclaredApiVersions.FirstOrDefault() 
                    ?? versionMetadata.ImplementedApiVersions.FirstOrDefault();
                
                if (apiVersion != null)
                {
                    endpoint.DisplayName = $"v{apiVersion.ToString()}_{baseName}";
                }
            }
        });
        return builder;
    }
}

// 使用示例
versionedGroup.MapGet("/common", () => "Common cross-version endpoint")
    .WithVersionedName("CommonEndpoint");

效果说明 #

通过以上方式，跨版本端点在不同API版本下会生成唯一的操作ID（如v1_CommonEndpoint、v2_CommonEndpoint），彻底避免名称冲突问题。

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