ASP.NET Core中Swashbuckle操作生成失败：类型冲突问题求助

问题根源 #

你使用的SchemaFilter仅能在生成Swagger Schema时隐藏属性，但Swashbuckle在生成Operation（接口操作定义）的阶段，会提前扫描模型的所有属性，包括那个引发冲突的Reverb.Product类型属性，所以仍然会触发类型冲突错误。要彻底解决，需要让Swashbuckle在模型解析阶段就完全忽略该属性，而不是仅在Schema显示阶段隐藏。

可行解决方案 #

方案1：用Json序列化特性直接忽略（最简单） #

如果该Reverb.Product类型属性本来就不需要在API响应中序列化，直接给属性标记[JsonIgnore]（对应Newtonsoft.Json）或[System.Text.Json.Serialization.JsonIgnore]（对应System.Text.Json）：

public class Product
{
    // 正常暴露的Product属性
    public int Id { get; set; }
    public string Name { get; set; }

    // 需要忽略的内部类属性
    [JsonIgnore]
    public Reverb.Product InternalProduct { get; set; }
}

这个方法会让序列化器和Swashbuckle同时忽略该属性，从根源上避免类型扫描冲突。

方案2：扩展自定义SwaggerExcludeAttribute，让Swashbuckle解析时忽略 #

如果你想保留自定义的SwaggerExcludeAttribute，需要让Swashbuckle在解析模型时就识别并跳过该属性，步骤如下：

1. 确保自定义特性标记在属性上：

[AttributeUsage(AttributeTargets.Property)]
public class SwaggerExcludeAttribute : Attribute { }

2. 编写自定义ContractResolver（针对Newtonsoft.Json，Swashbuckle默认用它）：

public class SwaggerExcludeContractResolver : DefaultContractResolver
{
    protected override JsonProperty CreateProperty(MemberInfo member, MemberSerialization memberSerialization)
    {
        var property = base.CreateProperty(member, memberSerialization);
        // 如果属性标记了SwaggerExcludeAttribute，就忽略它
        if (member.GetCustomAttribute<SwaggerExcludeAttribute>() != null)
        {
            property.Ignored = true;
        }
        return property;
    }
}

3. 在Swagger配置中指定这个ContractResolver：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    // 保留你原来的SchemaFilter（可选，因为ContractResolver已经会忽略属性）
    c.SchemaFilter<SwaggerExcludeFilter>();
    // 配置Swashbuckle使用自定义ContractResolver
    c.AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.ContractResolver = new SwaggerExcludeContractResolver();
    });
});

方案3：直接忽略整个Reverb.Product类型 #

如果Reverb.Product是纯内部类，完全不需要在Swagger中出现，可以直接让Swashbuckle忽略整个类型：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    // 忽略Reverb.Product类型
    c.IgnoreType<Reverb.Product>();
});

这个方法会让Swashbuckle完全不处理该类型，自然不会触发和同名Product的冲突。

验证方法 #

修改配置后，重新启动项目，访问Swagger UI，检查接口的Operation是否生成成功，同时确认Reverb.Product相关属性没有出现在任何Schema中。

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