ASP.NET Core可选路由参数在Scalar中显示为必填的问题排查

你遇到的问题是因为[ApiController]特性的默认行为：它会自动将路由参数标记为必填项，即使你在路由模板中添加了?并使用了可空类型参数。这导致OpenAPI文档（Scalar基于此生成界面）错误地将该参数识别为必填。

解决方案1：拆分端点（推荐，符合REST风格） #

将两种场景拆分为两个独立的HttpGet方法，这样Scalar能正确识别各自的参数要求，代码也更清晰：

[ApiController]
[Route("[controller]")]
public class CutlistsController : ControllerBase
{
    // 不传参数时返回全部条目
    [HttpGet]
    public ActionResult<IEnumerable<YourItemType>> GetAllItems()
    {
        // 实现返回全部条目的逻辑
        return Ok(/* 你的全量数据 */);
    }

    // 传入num时返回单个条目
    [HttpGet("{num:int}")]
    public ActionResult<YourItemType> GetSingleItem(int num)
    {
        // 实现根据num返回单个条目的逻辑
        return Ok(/* 单个条目数据 */);
    }
}

解决方案2：保留单方法，显式标记参数为可选 #

如果你坚持使用同一个方法处理两种场景，需要显式通过[FromRoute]特性覆盖[ApiController]的默认必填规则：

[ApiController]
[Route("[controller]")]
public class CutlistsController : ControllerBase
{
    [HttpGet("{num:int?}")]
    public ActionResult<object> Test([FromRoute(Required = false)] int? num)
    {
        if (num.HasValue)
        {
            // 返回单个条目逻辑
            return Ok(new { Id = num });
        }
        else
        {
            // 返回全部条目逻辑
            return Ok(/* 全量数据 */);
        }
    }
}

修改后重新启动服务，Scalar页面应该会正确将num标记为可选参数。

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