.NET 8极简API：同名不同命名空间对象致Swagger 500错误的解决问询

项目结构 #

Features
  Delete
    Handler.cs
    JsonRequest.cs
    JsonResponse.cs
  Get
    Handler.cs
    JsonRequest.cs
    JsonResponse.cs
  Post
    Handler.cs
    JsonRequest.cs
    JsonResponse.cs
  Put
    Handler.cs
    JsonRequest.cs
    JsonResponse.cs

问题现象 #

使用上述命名方式时，Swagger触发500错误，原因是API参数使用了同名但分属不同命名空间的JsonRequest类。相关冲突版本API代码如下：

public static async Task<IResult> PostUser(HttpContext httpContext, IMediator mediator, [FromBody] Post.JsonRequest jsonRequest)
{
    var request = new Post.Handler.Request(httpContext, jsonRequest);
    var response = await mediator.Send(request);
    return response.ResultForHttp;
}

public static async Task<IResult> PutUser(HttpContext httpContext,IMediator mediator,[FromBody] Put.JsonRequest jsonRequest)
{
    var request = new Put.Handler.Request(httpContext, jsonRequest);
    var response = await mediator.Send(request);
    return response.ResultForHttp;
}

public static async Task<IResult> DeleteUser(HttpContext httpContext, IMediator mediator, [FromBody] Delete.JsonRequest jsonRequest)
{
    var request = new Delete.Handler.Request(httpContext, jsonRequest);
    var response = await mediator.Send(request);
    return response.ResultForHttp;
}

将类名修改为唯一名称（如PostJsonRequest、PutJsonRequest）后，Swagger恢复正常：

public static async Task<IResult> PostUser(HttpContext httpContext, IMediator mediator, [FromBody] Post.PostJsonRequest jsonRequest)
{...}

public static async Task<IResult> PutUser(HttpContext httpContext,IMediator mediator,[FromBody] Put.PutJsonRequest jsonRequest)
{...}

public static async Task<IResult> DeleteUser(HttpContext httpContext, IMediator mediator, [FromBody] Delete.DeleteJsonRequest jsonRequest)
{...}

三类JsonRequest的实际差异（均继承自BaseJsonRequest）：

• DELETE请求类

namespace Api.Users.Features.Delete;
public class JsonRequest : BaseJsonRequest
{
    [JsonPropertyName("channel")] public ChannelDataJson ChannelData { get; set; } = new();
    [JsonPropertyName("userIdentifiers")] public List<string> UserIdentifiers { get; set; } = [];
}

• POST请求类

namespace Api.Users.Features.Post;
public class JsonRequest : BaseJsonRequest
{
    [JsonPropertyName("channel")] public ChannelDataJson ChannelData { get; set; } = new();
    [JsonPropertyName("users")] public List<FullUser> Users { get; set; } = [];
}

• PUT请求类

namespace Api.Users.Features.Put;
public class JsonRequest : BaseJsonRequest
{
    [JsonPropertyName("channel")] public ChannelDataJson ChannelData { get; set; } = new();
    [JsonPropertyName("users")] public List<FullUser> Users { get; set; } = [];

    [JsonPropertyName("lockAction")] public EnumLockAction Action { get; set; } = EnumLockAction.None;
}

解决方案：配置Swagger SchemaId生成策略 #

可以通过自定义Swagger的SchemaId生成逻辑，让它基于命名空间+类名生成唯一标识，避免同名类冲突。

在Program.cs中配置Swagger时，添加如下代码：

builder.Services.AddSwaggerGen(options =>
{
    // 自定义SchemaId生成规则，使用命名空间+类名确保唯一性
    options.CustomSchemaIds(type => 
    {
        // 对嵌套类做特殊处理，直接返回完整命名空间+类名
        return type.FullName?.Replace("+", ".") ?? type.Name;
    });
});

说明 #

• 默认情况下，Swagger仅使用类名作为SchemaId，导致不同命名空间的同名类生成重复的Schema，引发500错误。
• 自定义CustomSchemaIds后，会用完整的命名空间+类名（或处理后的唯一名称）作为SchemaId，确保每个类的Schema标识唯一。

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