Swashbuckle.AspNetCore升级后swagger.json的example含BOM字符格式错误

第一步：定位BOM来源 #

BOM字符（0xFEFF）是UTF-8编码的字节序标记，只会出现在文本内容开头，你遇到的每个example属性都带该字符，优先排查两个来源：

• 检查项目生成的XML注释文件：进入bin目录找到和程序集同名的.xml文件，用十六进制编辑器打开，查看<example>节点包裹的内容是否以0xFEFF开头。如果是，说明你的项目生成XML注释时默认添加了BOM，修改csproj文件的PropertyGroup节点，添加如下配置即可解决：

<GenerateDocumentationFile>true</GenerateDocumentationFile>
<DocumentationFileEncoding>utf-8</DocumentationFileEncoding>

如果配置不生效，可以添加生成后事件，用PowerShell将生成的XML文件转换为无BOM的UTF-8格式。

• 检查自定义Swagger示例类：你通过AddSwaggerExamplesFromAssemblyOf<DataRequestSwaggerExample>()注册的所有示例类，检查里面返回的字符串属性是否是从带BOM的文本文件读取，或者复制粘贴内容时不小心带入了隐藏的BOM字符。可以将示例字符串输出为十六进制确认，存在BOM的话直接重新编辑字符串内容即可。

第二步：通用兜底处理 #

如果排查后没有找到明确来源，直接添加一个Schema过滤器全局清理所有示例中的BOM字符即可，具体操作如下：

1. 定义过滤器类：

public class RemoveBomFromExampleFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 清理字符串类型示例的BOM
        if (schema.Example is OpenApiString strExample)
        {
            var cleanedValue = strExample.Value.TrimStart('\uFEFF');
            schema.Example = new OpenApiString(cleanedValue);
        }
        // 递归处理嵌套属性的示例
        if (schema.Properties?.Count > 0)
        {
            foreach (var prop in schema.Properties.Values)
            {
                Apply(prop, context);
            }
        }
    }
}

2. 在SwaggerGen配置中注册过滤器：
   在你现有的AddSwaggerGen配置块里添加一行：

options.SchemaFilter<RemoveBomFromExampleFilter>();

补充说明 #

你在其他项目无法复现的原因是：其他项目的XML注释、示例字符串本身都没有携带BOM字符，该问题和Swashbuckle版本没有直接关联，只是6.x版本的序列化逻辑不会自动过滤字符串中携带的BOM字符，才会直接写入swagger.json导致格式非法。

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