ASP.NET Web API中Swagger模型预览显示私有字段名（带Field后缀）问题

核心原因 #

1. 序列化器配置错误：Swagger依赖的JSON序列化器（Newtonsoft.Json或System.Text.Json）被配置为序列化私有字段，而非默认的公开属性。比如开启了IncludeFields选项，导致字段被纳入序列化范围。
2. Xml序列化特性干扰：你的contact类是从XSD自动生成的，带有XmlSerializer相关特性（如XmlTypeAttribute、XmlRootAttribute）。Swashbuckle在生成Schema时，可能误将Xml序列化的字段映射规则当成JSON序列化规则，优先抓取私有字段。
3. Swashbuckle配置异常：Swagger的Schema生成器被修改了默认规则，导致扫描并展示了类的私有成员。

解决办法 #

1. 修正JSON序列化器配置 #

针对Newtonsoft.Json（ASP.NET Core早期版本常用）

在Startup/Program.cs中确保序列化器只序列化公开属性：

services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        // 使用默认的属性序列化规则，不要开启字段序列化
        options.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
        // 确保以下配置不存在或设为false
        // options.SerializerSettings.IncludeFields = true;
    });

针对System.Text.Json（ASP.NET Core 3.0+默认）

检查并关闭字段序列化：

services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 默认就是false，确保没有被改成true
        options.JsonSerializerOptions.IncludeFields = false;
    });

2. 自定义Swashbuckle Schema过滤规则 #

通过自定义Filter强制Swagger只展示公开属性：

// 在Swagger配置中添加Filter
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    c.SchemaFilter<PublicPropertiesOnlyFilter>();
});

// 实现自定义SchemaFilter
public class PublicPropertiesOnlyFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (schema.Properties == null) return;

        // 获取类的所有公开属性名称
        var publicPropertyNames = context.Type
            .GetProperties(BindingFlags.Public | BindingFlags.Instance)
            .Select(p => p.Name);

        // 移除非公开属性对应的Schema项
        var propertiesToRemove = schema.Properties
            .Where(p => !publicPropertyNames.Contains(p.Key))
            .ToList();
        
        foreach (var prop in propertiesToRemove)
        {
            schema.Properties.Remove(prop.Key);
        }
    }
}

3. 优化自动生成的类 #

如果是用xsd.exe生成的类，添加/properties参数重新生成，确保生成的类正确关联属性的序列化规则：

xsd.exe ContactSchema.xsd /c /properties

这样生成的类会更友好地支持JSON序列化，避免Swagger误抓私有字段。

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