Swashbuckle中XML注释配置的example值为何不在Swagger UI显示？

问题场景 #

使用Swashbuckle框架生成接口文档时，在XML文档注释的param标签中添加example属性配置参数示例，对应接口代码如下：

/// <summary>Gets a user by id.</summary>
/// <param name="id" example="this does not work">The id of user.</param>
/// <returns>got user.</returns>
[HttpGet("Get")]
[ProducesResponseType(typeof(UserDTO), 200)]
[ProducesResponseType(typeof(AppException), StatusCodes.Status500InternalServerError)]
public async Task<IActionResult> Get(string id)
{
    return HandleResult(await _userServices.GetUserAsync(id));
}

配置完成后，设置的example示例值并未在Swagger UI中正常展示，界面效果如下：

排查方向 #

• 确认Swashbuckle原生能力边界：Swashbuckle默认的XML注释解析逻辑不支持识别<param>标签上的自定义example属性。example不属于C#官方XML文档注释的标准属性，默认解析逻辑只会提取param标签内的文本作为参数描述，不会读取标签上的自定义属性，这是该问题最核心的常见诱因。如果要实现参数示例展示，有两种成熟方案：一是自行实现IParameterFilter，在过滤器中加载XML文档、读取对应param节点的example属性赋值给参数的Example字段；二是引入Swashbuckle.AspNetCore.Annotations包，通过[SwaggerParameter(Example = "xxx")]特性配置示例值，针对复杂类型参数也可以通过[Example]特性统一配置。
• 校验XML注释文件的加载配置：右键项目进入属性页，确认「生成」板块下已勾选「XML文档文件」选项，且没有配置取消警告的规则过滤XML注释相关提示；同时检查Program/Startup中Swagger生成器的配置，确认IncludeXmlComments方法传入的XML文件路径正确、文件存在且可正常读取。如果参数的文本描述已经能在Swagger UI中正常展示，仅示例值不显示，可以直接跳过本项排查。
• 排查自定义过滤器的覆盖问题：如果项目中自行实现了IOperationFilter、IParameterFilter、IDocumentFilter等扩展逻辑，检查过滤器的执行顺序，确认后续执行的过滤器没有把参数的Example字段重新赋值为空或者默认值，覆盖了XML解析逻辑的输出。
• 校验参数绑定场景匹配：如果参数是从请求Body绑定的复杂类型参数，param标签上的配置本身就不会作用于Body级别的参数示例，这类场景需要针对DTO类型单独配置示例值，不能依赖接口方法上的param标签属性。
• 排除缓存干扰：清理浏览器本地缓存、重启应用服务后强制刷新Swagger UI页面，排除前端静态资源缓存、Swagger文档接口缓存导致的配置不生效问题。

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