ASP.NET Core 6中如何为Swagger指定自定义请求模型类型？

在ASP.NET Core + Swashbuckle的场景下，没有直接对应[ProducesResponseType]的请求类型指定属性，但可以通过自定义Swagger操作过滤器实现需求，以下是两种灵活的实现方式：

方式一：全局批量替换参数类型 #

如果需要统一替换特定参数类型的Swagger显示，可创建全局操作过滤器：

1. 实现IOperationFilter接口：

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

public class ReplaceRequestBodyTypeFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 定位目标参数：CartItem类型的FromBody参数
        var targetParam = context.ApiDescription.ParameterDescriptions
            .FirstOrDefault(p => p.ParameterType == typeof(CartItem) && p.Source == BindingSource.Body);
        
        if (targetParam != null && operation.RequestBody != null)
        {
            // 生成CartItemRequest对应的Swagger Schema
            var requestSchema = context.SchemaGenerator.GenerateSchema(typeof(CartItemRequest), context.SchemaRepository);
            // 替换请求体的Schema定义
            operation.RequestBody.Content["application/json"].Schema = requestSchema;
        }
    }
}

2. 在Swagger注册时添加该过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<ReplaceRequestBodyTypeFilter>();
    // 其他Swagger配置项...
});

方式二：自定义属性精准控制单个参数 #

如果需要针对特定参数单独指定显示类型，可通过自定义标记属性配合过滤器实现：

1. 定义自定义标记属性：

[AttributeUsage(AttributeTargets.Parameter)]
public class SwaggerRequestTypeAttribute : Attribute
{
    public Type TargetType { get; }
    public SwaggerRequestTypeAttribute(Type targetType)
    {
        TargetType = targetType;
    }
}

2. 修改控制器参数，添加该属性：

[HttpPut("put-item/{customerId}")]
[ProducesResponseType(400)]
[ProducesResponseType(404)]
[ProducesResponseType(200)]
public async Task<IActionResult> PutItemToCart(
    [GuidId] Guid customerId, 
    [FromBody] [SwaggerRequestType(typeof(CartItemRequest))] CartItem item)
{
    // 原有业务逻辑代码...
}

3. 实现对应的操作过滤器：

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

public class CustomRequestTypeFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        foreach (var paramDesc in context.ApiDescription.ParameterDescriptions)
        {
            // 检查参数是否带有自定义标记属性
            var attr = paramDesc.ParameterInfo?.GetCustomAttribute<SwaggerRequestTypeAttribute>();
            if (attr != null && paramDesc.Source == BindingSource.Body && operation.RequestBody != null)
            {
                // 生成目标类型的Schema并替换原有定义
                var targetSchema = context.SchemaGenerator.GenerateSchema(attr.TargetType, context.SchemaRepository);
                operation.RequestBody.Content["application/json"].Schema = targetSchema;
            }
        }
    }
}

4. 注册过滤器到Swagger：

builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<CustomRequestTypeFilter>();
    // 其他Swagger配置项...
});

两种方式都能让Swagger界面显示CartItemRequest作为请求体模型，同时完全不影响后端自定义模型绑定器对CartItem类型的处理逻辑。

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