.NET Core 5.0中如何在Swagger描述中添加加粗文字？

问题原因 #

默认情况下，Swashbuckle（.NET生态的Swagger实现）对XML注释的处理逻辑是转义HTML标签，同时不解析Markdown语法。这就导致你测试的<strong>、<b>会被转成纯文本显示，**、__这类Markdown加粗标记也不会被识别渲染。

解决方法 #

要实现注释里的文字加粗，需要通过配置让Swashbuckle支持HTML标签或Markdown语法，以下是两种可行方案：

方案1：允许HTML标签渲染 #

在项目的Startup.cs（或Program.cs，取决于项目结构）中修改Swagger配置，添加自定义文档过滤器来取消HTML标签转义：

services.AddSwaggerGen(c =>
{
    // 加载项目XML注释文件
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath, true);

    // 注册自定义过滤器，允许HTML渲染
    c.DocumentFilter<AllowHtmlInCommentsDocumentFilter>();
});

// 自定义文档过滤器类
public class AllowHtmlInCommentsDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var path in swaggerDoc.Paths.Values)
        {
            HandleOperation(path.Operations);
        }
    }

    private void HandleOperation(IDictionary<OperationType, OpenApiOperation> operations)
    {
        if (operations == null) return;
        foreach (var operation in operations.Values)
        {
            // 处理接口摘要
            if (!string.IsNullOrEmpty(operation.Summary))
            {
                operation.Summary = System.Web.HttpUtility.HtmlDecode(operation.Summary);
            }
            // 处理接口描述
            if (!string.IsNullOrEmpty(operation.Description))
            {
                operation.Description = System.Web.HttpUtility.HtmlDecode(operation.Description);
            }
            // 处理参数注释
            foreach (var parameter in operation.Parameters)
            {
                if (!string.IsNullOrEmpty(parameter.Description))
                {
                    parameter.Description = System.Web.HttpUtility.HtmlDecode(parameter.Description);
                }
            }
        }
    }
}

配置完成后，你就可以在XML注释里使用<strong>或<b>标签实现加粗：

/// <summary>
/// 这是一个测试 <strong>加粗文本1</strong>, <b>加粗文本2</b>
/// </summary>
/// <returns></returns>

方案2：支持Markdown语法 #

如果你偏好使用Markdown的**加粗语法，可以借助Markdig库将Markdown转换为HTML：

1. 安装NuGet包：Markdig
2. 修改上述自定义过滤器，添加Markdown解析逻辑：

// 处理接口摘要：先解码HTML再解析Markdown
if (!string.IsNullOrEmpty(operation.Summary))
{
    operation.Summary = Markdig.Markdown.ToHtml(System.Web.HttpUtility.HtmlDecode(operation.Summary));
}
// 处理接口描述同理
if (!string.IsNullOrEmpty(operation.Description))
{
    operation.Description = Markdig.Markdown.ToHtml(System.Web.HttpUtility.HtmlDecode(operation.Description));
}

之后就可以用**加粗文本3**这类Markdown语法实现加粗效果了。

注意事项 #

• 确保已启用XML注释生成：在项目属性的「生成」选项卡中，勾选「XML文档文件」并设置正确的生成路径。
• .NET Core 5.0建议搭配5.x系列的Swashbuckle包，避免版本兼容问题。

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