Web API可选路由参数在Swagger UI默认取值为逗号的原因咨询

先看你的API控制器代码：

[HttpGet("{xyz}/{reason?}")]
public async Task<IActionResult> HttpGet([FromRoute] string xyz, string reason=null)
{
    // implementation code here
}

问题原因 #

核心问题出在路由中可选参数的定义方式和Swagger UI的解析逻辑差异：

• ASP.NET Core本身处理路由时，若可选路由段reason未提供，会正确将参数值设为null，这就是Postman调用正常的原因。
• 但Swagger UI在生成请求URL时，对路由内的可选参数处理有缺陷：当你不在Swagger的输入框中填写reason值时，它会自动用逗号,填充这个空的路由段位置，导致后端接收到的reason参数变成逗号。这是因为Swagger的OpenAPI生成逻辑无法正确识别空路由段应对应null，而是用了默认的占位符填充。

解决办法 #

有两种简单可行的处理方式：

1. 将可选参数改为查询参数：修改路由模板为[HttpGet("{xyz}")]，同时给reason参数加上[FromQuery]标记，代码如下：

   [HttpGet("{xyz}")]
   public async Task<IActionResult> HttpGet([FromRoute] string xyz, [FromQuery] string reason=null)
   {
       // implementation code here
   }
   

   这种方式下，Swagger会正确生成可选的查询参数，不会出现默认逗号的问题。
2. 调整Swagger配置（复杂选项）：如果必须保留路由参数结构，可以在Swagger的配置中添加自定义操作过滤器，手动修正可选路由段的生成逻辑，确保未提供参数时不填充任何内容。不过这种方式配置成本较高，不如第一种直接。

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