如何在ASP.NET Core应用中配置Swagger UI的useUnsafeMarkdown参数？

适用场景 #

Swagger UI默认的HTML消毒规则会移除文档内容中的内联style属性、class属性、data-*属性，当需要在接口文档中保留这些属性的渲染效果时，可通过开启useUnsafeMarkdown配置调整过滤逻辑。

核心配置步骤 #

ASP.NET Core生态中最常用的Swagger UI集成组件为Swashbuckle.AspNetCore，所有参数配置均在Swagger UI中间件注册环节完成：

• 定位到项目中Swagger UI中间件的注册代码，即包含app.UseSwaggerUI()方法的代码块，根据项目结构不同，该代码块可能位于Startup.cs的Configure方法（.NET 5及更早版本），或Program.cs的顶级语句流程中（.NET 6+版本）
• 在UseSwaggerUI方法的配置委托内，通过ConfigObject字典传入目标配置项，将useUnsafeMarkdown值设为true

代码示例 #

.NET 6+ 版本（顶级语句模式） #

//  Program.cs 中的Swagger UI配置段
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "项目API文档 v1");
    //  核心配置：开启非安全Markdown渲染模式
    c.ConfigObject["useUnsafeMarkdown"] = true;
});

.NET 5及更早版本（Startup类模式） #

//  Startup.cs -> Configure 方法
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ... 其他中间件注册逻辑
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.RoutePrefix = "swagger";
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "项目API文档 v1");
        //  核心配置：开启非安全Markdown渲染模式
        c.ConfigObject["useUnsafeMarkdown"] = true;
    });
}

注意事项 #

• 旧版本兼容提示：如果使用的Swashbuckle.AspNetCore版本低于6.0.0，前端可能无法直接解析布尔类型的配置值，需将值调整为字符串格式传入，即c.ConfigObject["useUnsafeMarkdown"] = "true";
• 安全风险提示：该配置会跳过Swagger UI默认的XSS过滤逻辑，如果文档内容包含不可信来源的HTML/Markdown片段，开启后可能存在跨站脚本攻击风险，仅建议在内部可信的文档场景下启用。

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