如何配置Swagger将关联对象设为只读并隐藏于POST/PUT请求UI

使用Swagger和EF Core配置外键后，POST/PUT请求的Swagger UI中会显示Class导航属性对象。即使添加了[SwaggerSchema(ReadOnly = true)]特性和自定义ISchemaFilter，创建ClassSection时该对象仍会显示。需要配置Swagger，让Class属性在POST/PUT请求的UI中不被包含。

当前代码 #

ClassSection模型 #

public class ClassSection
{
    [Key]
    public int Id { get; set; }

    [ForeignKey(nameof(Id))]
    public int ProfessorId { get; set; }

    [ForeignKey("Class")]
    public int ClassId { get; set; }

    [SwaggerSchema(ReadOnly = true)]
    public Class Class { get; set; } 

    [Required]
    public int Section { get; set; }

    [Required]
    public DateTime StartTime { get; set; }

    [Required]
    public DateTime EndTime { get; set; }

    [Required]
    public string Building { get; set; }

    [Required]
    public int Room { get; set; }

    [Required]
    public int Capacity { get; set; }
}

自定义Swagger过滤器 #

public class SwaggerFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(ClassSection))
        {
            schema.Properties["class"].ReadOnly = true;
        }
    }
}

Program.cs中的Swagger配置 #

builder.Services.AddSwaggerGen(options =>
{
    options.EnableAnnotations();
    options.SchemaFilter<SwaggerFilter>();
});

方法1：使用数据传输对象(DTO)（推荐） #

为POST/PUT请求创建专用DTO，仅包含业务所需字段，避免直接暴露EF Core实体的导航属性。

创建ClassSectionCreateDto #

public class ClassSectionCreateDto
{
    [Required]
    public int ProfessorId { get; set; }

    [Required]
    public int ClassId { get; set; }

    [Required]
    public int Section { get; set; }

    [Required]
    public DateTime StartTime { get; set; }

    [Required]
    public DateTime EndTime { get; set; }

    [Required]
    public string Building { get; set; }

    [Required]
    public int Room { get; set; }

    [Required]
    public int Capacity { get; set; }
}

修改控制器接口 #

在POST/PUT方法中使用DTO作为参数，再映射为实体进行数据库操作：

[HttpPost]
public async Task<IActionResult> CreateClassSection([FromBody] ClassSectionCreateDto dto)
{
    var classSection = new ClassSection
    {
        ProfessorId = dto.ProfessorId,
        ClassId = dto.ClassId,
        Section = dto.Section,
        StartTime = dto.StartTime,
        EndTime = dto.EndTime,
        Building = dto.Building,
        Room = dto.Room,
        Capacity = dto.Capacity
    };

    _context.ClassSections.Add(classSection);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(GetClassSection), new { id = classSection.Id }, classSection);
}

此方法不仅解决Swagger显示问题，还能避免过度暴露实体属性，符合分层架构最佳实践。

方法2：修改Swagger过滤器移除属性 #

若不想创建DTO，可修改ISchemaFilter，在POST/PUT请求的Schema中直接移除Class属性：

public class SwaggerFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(ClassSection) && schema.Properties.ContainsKey("class"))
        {
            // 移除Class属性，不在Swagger请求体中显示
            schema.Properties.Remove("class");
        }
    }
}

如果需要在GET响应中保留Class属性，可通过判断请求类型实现差异化处理：

public class SwaggerFilter : ISchemaFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public SwaggerFilter(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type != typeof(ClassSection)) return;

        var httpMethod = _httpContextAccessor.HttpContext?.Request.Method;
        if (httpMethod is "POST" or "PUT")
        {
            // POST/PUT请求移除Class属性
            schema.Properties.Remove("class");
        }
        else
        {
            // 其他请求设置为只读
            if (schema.Properties.TryGetValue("class", out var classProp))
            {
                classProp.ReadOnly = true;
            }
        }
    }
}

记得在Program.cs中注册IHttpContextAccessor：

builder.Services.AddHttpContextAccessor();

方法3：使用JsonIgnore特性 #

若Class属性无需在任何序列化场景（请求/响应）中出现，可添加[JsonIgnore]特性：

[SwaggerSchema(ReadOnly = true)]
[JsonIgnore]
public Class Class { get; set; }

注意：此特性会让Class在GET响应中也不显示，如需保留响应中的该属性，请勿使用此方法。

方法4：使用SwaggerSchema的Ignore属性 #

直接通过SwaggerSchema特性标记忽略该属性：

[SwaggerSchema(ReadOnly = true, Ignore = true)]
public Class Class { get; set; }

需确保已启用Swagger注解（options.EnableAnnotations()）才能生效。

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