.NET Core API中字符串类型查询参数Swagger Required标记未被识别问题

我之前也踩过这个一模一样的坑！在.NET Core API里给字符串类型的查询参数加了必填标记，Swagger却死活不显示必填星号，但int、bool这类其他数据类型的必填参数却正常，这其实是因为字符串作为简单类型，默认的模型绑定和Swagger的解析逻辑有特殊处理，下面给你几个实用的解决方案：

1. 用[BindRequired]替换/配合[Required] #

字符串作为查询参数时，默认模型绑定会把null自动转为空字符串，这会导致[Required]的校验逻辑不触发，Swagger也不会识别它为必填。而[BindRequired]是强制要求绑定源必须提供这个参数，Swagger能正确识别这个标记：

[HttpGet("user/detail")]
public IActionResult GetUserDetail([BindRequired, FromQuery] string userId)
{
    // 业务逻辑
    return Ok($"用户ID：{userId}");
}

这样设置后，Swagger里的userId参数会显示必填星号，同时如果请求时没传这个参数，API会直接返回400错误。

2. 将查询参数封装到模型类中 #

如果你的接口有多个查询参数，把它们封装成模型类是更优雅的做法，而且在模型的字符串属性上添加[Required]，Swagger会自动识别为必填：

// 查询参数模型
public class UserQueryModel
{
    [Required(ErrorMessage = "用户ID不能为空")]
    public string UserId { get; set; }
    
    public int? Age { get; set; }
}

// 接口方法
[HttpGet("user/list")]
public IActionResult GetUserList([FromQuery] UserQueryModel queryModel)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }
    // 业务逻辑
    return Ok(queryModel);
}

这种方式不仅能让Swagger正确识别必填参数，还能统一做模型校验，代码结构更清晰。

3. 自定义Swagger Schema过滤器（适合不想改业务代码的场景） #

如果不想调整现有代码结构，可以通过自定义Swagger的Schema过滤器，强制识别带[Required]的字符串查询参数：

首先在Program.cs（或Startup.cs）里配置Swagger时添加过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "我的API", Version = "v1" });
    // 注册自定义过滤器
    c.SchemaFilter<RequiredStringParamFilter>();
});

// 实现过滤器逻辑
public class RequiredStringParamFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 检查是否是查询参数且带有[Required]特性
        if (context.ParameterInfo != null 
            && context.ParameterInfo.ParameterType == typeof(string)
            && context.ParameterInfo.GetCustomAttributes(typeof(RequiredAttribute), true).Any())
        {
            schema.Required.Add(context.ParameterInfo.Name);
        }
    }
}

这个过滤器会遍历所有参数，把带[Required]的字符串查询参数手动加入Swagger的必填列表。

额外注意点 #

• 确保给查询参数显式添加[FromQuery]标记，隐式绑定可能导致Swagger识别异常；
• 检查你的Swashbuckle.AspNetCore版本是否和.NET Core版本兼容，版本不匹配也可能出现这类识别问题。

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