求助：Swashbuckle无法显示自定义类型属性的注释信息

我之前也碰到过完全一样的情况——内置类型、集合类型的属性注释都能正常显示，唯独单个自定义类型的属性注释死活不出来。下面是我亲测有效的解决方法：

第一步：让项目生成XML注释文件 #

Swashbuckle依赖XML注释文件来读取代码里的注释，所以首先得开启这个功能：

• 右键你的项目 → 选择「属性」
• 切换到「生成」选项卡
• 在「输出」区域里，勾选「XML文档文件」，可以保留默认路径（一般是$(OutputPath)$(AssemblyName).xml），也可以自己指定位置

第二步：配置Swashbuckle读取XML注释 #

在Program.cs（旧项目是Startup.cs）里找到Swagger的配置代码，添加读取XML文件的逻辑：

using System.Reflection;

builder.Services.AddSwaggerGen(c =>
{
    // 拼接当前项目的XML注释文件路径
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    
    // 让Swagger加载XML注释，includeControllerXmlComments设为true可以同时读取控制器的注释
    c.IncludeXmlComments(xmlFilePath, includeControllerXmlComments: true);

    // 如果Order、OrderLine这类实体类在单独的类库项目里，还要添加对应类库的XML文件路径
    // var libraryXmlFileName = "YourLibraryAssemblyName.xml";
    // var libraryXmlFilePath = Path.Combine(AppContext.BaseDirectory, libraryXmlFileName);
    // c.IncludeXmlComments(libraryXmlFilePath);
});

第三步：（可选）用自定义SchemaFilter强制提取属性注释 #

如果上面的步骤做完后，单个自定义类型的属性注释还是不显示，那可能是Swashbuckle默认的注释提取逻辑漏掉了这类属性。这时候可以写一个自定义SchemaFilter来手动提取：

先创建Filter类：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Reflection;
using System.Xml.Linq;

public class CustomPropertySchemaFilter : ISchemaFilter
{
    private readonly XDocument _xmlDoc;

    public CustomPropertySchemaFilter(string xmlFilePath)
    {
        if (File.Exists(xmlFilePath))
        {
            _xmlDoc = XDocument.Load(xmlFilePath);
        }
    }

    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 只处理属性成员
        var propertyInfo = context.MemberInfo as PropertyInfo;
        if (propertyInfo == null || _xmlDoc == null) return;

        // 拼接XML注释里的成员路径
        var memberPath = $"P:{propertyInfo.DeclaringType.FullName}.{propertyInfo.Name}";
        var commentNode = _xmlDoc.Descendants("member")
            .FirstOrDefault(m => m.Attribute("name")?.Value == memberPath);

        // 如果找到注释节点，把summary内容设为属性的描述
        if (commentNode != null)
        {
            var summaryNode = commentNode.Element("summary");
            if (summaryNode != null)
            {
                schema.Description = summaryNode.Value.Trim();
            }
        }
    }
}

然后在Swagger配置里注册这个Filter：

builder.Services.AddSwaggerGen(c =>
{
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    
    c.IncludeXmlComments(xmlFilePath, includeControllerXmlComments: true);
    
    // 注册自定义SchemaFilter，传入XML文件路径
    c.SchemaFilter<CustomPropertySchemaFilter>(xmlFilePath);
});

做完这些操作后，你的OneOrderLine属性的注释应该就能在Swagger UI里正常显示了。

内容的提问来源于stack exchange，提问作者Mathias Rönnlund