.NET Core中Swagger未正确处理可选参数的问题排查与解决

问题原因 #

• 核心问题出在Swashbuckle（.NET生态的Swagger实现）对路由可选参数的解析逻辑：虽然你在路由中用?标记参数可选，方法参数也设置了默认值null，但Swagger默认会将路由参数识别为必填项——它认为路由参数是请求路径的组成部分，除非明确配置或调整参数绑定方式，否则不会自动识别其可选性。
• 另外，路由参数的绑定优先级高于查询参数，当参数仅关联路由时，Swagger无法通过默认值判断它是可选的，因为路由路径的匹配逻辑会优先检查参数是否存在。

解决方法 #

方法1：将可选参数改为查询参数（推荐） #

如果该参数不需要作为路由路径的一部分，直接改为查询参数，Swagger会自动识别为可选：

[HttpGet("getOrder")]
public async Task<IEnumerable<Product>> Get([FromQuery] int? price = null)
{
    // 业务逻辑
}

请求可以是/getOrder（不带参数）或/getOrder?price=100（带参数），Swagger会正确标记price为可选。

方法2：保留路由可选参数，添加绑定标记 #

若必须保留路由中的可选参数，给方法参数加上[FromRoute]标记，明确参数来自路由，Swagger就能识别其可选性：

[HttpGet]
[Route("getOrder/{price?}")]
public async Task<IEnumerable<Product>> Get([FromRoute] int? price = null)
{
    // 业务逻辑
}

方法3：配置Swagger自定义过滤器强制标记为可选 #

如果上述方法不生效，可添加自定义操作过滤器，让Swagger扫描路由中的?标记，将对应参数设为非必填：
在Swagger配置代码（如Program.cs）中添加：

builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<OptionalRouteParamFilter>();
});

// 自定义过滤器类
public class OptionalRouteParamFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 提取路由中带?的参数名
        var optionalRouteParams = context.ApiDescription.RelativePath.Split('/')
            .Where(segment => segment.EndsWith("?"))
            .Select(segment => segment.TrimEnd('?'));

        // 将对应Swagger参数设为非必填
        foreach (var param in operation.Parameters.Where(p => optionalRouteParams.Contains(p.Name)))
        {
            param.Required = false;
        }
    }
}

方法4：定义多路由覆盖两种场景 #

直接添加两个路由，分别对应带参数和不带参数的情况，Swagger会生成两个接口选项：

[HttpGet]
[Route("getOrder")]
[Route("getOrder/{price}")]
public async Task<IEnumerable<Product>> Get(int? price = null)
{
    // 业务逻辑
}

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