如何在Swagger请求体示例中隐藏属性但响应示例仍保留该属性

以下是3种常用的实现方案，你可以根据自己的项目版本和需求选择：

方案1：使用Swagger原生特性（最简单，推荐） #

直接给ID属性添加[SwaggerSchema]特性标记为只读，Swagger会自动区分请求/响应的展示逻辑：

1. 先引用对应命名空间

using Swashbuckle.AspNetCore.Annotations;

2. 调整ViewModel属性

public class PersonViewModel
{
    // 标记为只读，仅在响应中展示
    [SwaggerSchema(ReadOnly = true)]
    public int? ID { get; set; }
    public string Name { get; set; }
}

配置后Swagger会自动在请求体示例中隐藏ID属性，响应示例中正常保留，不影响实际接口的序列化逻辑。

方案2：自定义Schema过滤器（灵活适配复杂场景） #

如果需要批量处理多个类的同类属性，不想给每个属性加特性，可以自定义Swagger的Schema过滤器：

1. 新建过滤器类

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class RemoveReadOnlyPropertyInRequestFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 匹配你要处理的ViewModel类型
        if (context.Type == typeof(PersonViewModel))
        {
            // 请求Schema会触发该逻辑，移除ID属性
            if (schema.Properties.TryGetValue("id", out _) || schema.Properties.TryGetValue("iD", out _))
            {
                // 注意属性名的大小写，根据你项目的Json序列化配置调整
                schema.Properties.Remove("id");
                schema.Properties.Remove("iD");
                // 如果ID被设为必填项，同步移除必填校验
                schema.Required.Remove("id");
                schema.Required.Remove("iD");
            }
        }
    }
}

2. 在Swagger配置中注册过滤器

// .NET 6+  Program.cs中配置
builder.Services.AddSwaggerGen(opt =>
{
    opt.SchemaFilter<RemoveReadOnlyPropertyInRequestFilter>();
});

方案3：拆分请求/响应ViewModel（架构层面最佳实践） #

如果你的项目可以调整代码结构，最稳妥的方案是拆分入参和出参的模型，完全避免混淆：

// 入参模型，仅包含请求方需要传入的字段
public class CreatePersonRequest
{
    public string Name { get; set; }
}

// 出参模型，包含后端生成的ID和其他返回字段
public class PersonResponse
{
    public int? ID { get; set; }
    public string Name { get; set; }
}

接口定义直接对应不同模型即可，不需要任何Swagger额外配置，逻辑更清晰，后续维护成本更低。

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