如何在.NET的Swashbuckle-swagger接口端点下方添加可折叠的大段说明文本

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

• 右键你的.NET项目 → 选择「属性」→ 切换到「生成」选项卡
• 找到「输出」板块，勾选「XML文档文件」，自动生成的默认路径无需修改
• 在「禁止显示警告」输入框中添加1591，避免未加注释的类/方法触发编译警告

步骤2：Swagger配置加载XML注释 #

在.NET 6+的Program.cs中注册Swagger服务时添加XML注释加载逻辑，示例代码如下：

using System.Reflection;

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
    {
        Title = "你的接口文档标题",
        Version = "v1"
    });

    // 加载当前项目的XML注释文件，第二个参数设为true才能读取控制器、接口方法的注释
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    options.IncludeXmlComments(xmlFilePath, true);
});

步骤3：添加对应说明文本 #

你截图中标注的待添加位置，对应XML注释中的<remarks>节点内容，该内容默认会显示在接口名称下方，端点折叠时自动隐藏，完全符合需求：

• 如果是给单个接口添加说明，直接在对应Action方法上方加<remarks>注释即可：

/// <summary>
/// 这是接口旁显示的短描述
/// </summary>
/// <remarks>
/// 这里就是你要添加的大段说明文本，会渲染在接口名称下方：
/// - 支持换行、列表、简单Markdown格式
/// - 端点折叠时该内容会同步隐藏
/// </remarks>
[HttpGet("test")]
public IActionResult TestApi()
{
    return Ok();
}

• 如果是要给整个控制器添加分组级别的说明，直接在控制器类上方加注释即可：

/// <summary>
/// 用户模块相关接口
/// </summary>
/// <remarks>
/// 该模块下所有接口都需要携带鉴权请求头
/// </remarks>
[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
    // 接口方法
}

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