C# Swashbuckle生成Swagger文档不显示<returns>注释如何解决

该功能可正常实现，Swashbuckle.AspNetCore原生支持解析<returns>注释节点，只需按以下步骤配置即可：

步骤1：确认项目开启XML文档生成 #

• 右键API项目，选择「属性」→「生成」
• 在「输出」区块勾选「XML文档文件」，路径建议使用通用格式：bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml
• 在「禁止显示警告」输入框添加1591，避免无注释的类/方法触发编译警告

步骤2：配置Swagger生成规则 #

如果你使用的是.NET 6+的顶级语句模式（Program.cs），按以下方式修改Swagger注入代码：

builder.Services.AddSwaggerGen(options =>
{
    // 替换为你的项目XML文件名，和步骤1生成的文件名一致
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFullPath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    // 第二个参数设为true，开启控制器/接口方法的XML注释解析，原生支持<returns>节点映射
    options.IncludeXmlComments(xmlFullPath, true);
});

如果配置后仍不生效，可添加自定义操作过滤器强制映射：

自定义操作过滤器代码 #

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

public class XmlReturnsOperationFilter : IOperationFilter
{
    private readonly XPathNavigator _xmlNav;

    public XmlReturnsOperationFilter(string xmlPath)
    {
        _xmlNav = new XPathDocument(xmlPath).CreateNavigator();
    }

    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var method = context.MethodInfo;
        if (method == null) return;

        // 构造XML注释的方法节点标识
        var memberId = $"M:{method.DeclaringType.FullName}.{method.Name}";
        var paramList = method.GetParameters();
        if (paramList.Any())
        {
            memberId += $"({string.Join(",", paramList.Select(p => p.ParameterType.FullName))})";
        }

        // 读取<returns>节点内容
        var returnsNode = _xmlNav.SelectSingleNode($"/doc/members/member[@name='{memberId}']/returns");
        if (returnsNode != null && operation.Responses.TryGetValue("200", out var successRes))
        {
            successRes.Description = returnsNode.Value.Trim();
        }
    }
}

注册过滤器 #

builder.Services.AddSwaggerGen(options =>
{
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFullPath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    options.IncludeXmlComments(xmlFullPath, true);
    // 注册自定义过滤器，传入XML文件路径
    options.OperationFilter<XmlReturnsOperationFilter>(xmlFullPath);
});

配置完成后重新生成项目，即可看到200响应的description字段已替换为<returns>节点中的内容。

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