Swagger文档可用的XML标签/函数有哪些？含表格语法疑问

刚好对Swashbuckle生成Swagger文档的XML用法比较熟悉，来帮你理清这些问题：

一、常用XML注释标签（Swashbuckle兼容） #

Swashbuckle（.NET生态下的Swagger工具）主要基于.NET通用XML注释生成文档，同时也提供了专属扩展标签：

通用.NET XML注释标签（Swashbuckle直接支持） #

• <summary>：给接口、类或方法添加简短描述，会直接显示在Swagger UI的接口列表顶部，帮用户快速了解接口用途
• <remarks>：用于撰写详细说明，重点支持Markdown格式，适合放置复杂逻辑解释、示例或表格内容
• <param name="参数名">：描述方法的每个输入参数，对应Swagger文档中参数的说明文本
• <returns>：说明方法返回值的类型与含义
• <example>：为参数或返回值指定示例值，部分版本需配合Swashbuckle扩展配置才能完全生效
• <exception cref="异常类型">：标注方法可能抛出的异常类型与触发场景

Swashbuckle专属扩展标签 #

这些是Swashbuckle独有的功能，需在项目中配置好Swashbuckle后才能生效：

• <swaggerOperation>：可自定义接口的Swashbuckle属性，比如设置operationId、指定tags对接口分类
• <swaggerResponse>：自定义特定响应状态码的描述，例如<swaggerResponse code="400" description="参数格式错误或必填项缺失" />
• <ignore>：标记某个类、方法或参数，避免Swashbuckle将其纳入生成的Swagger文档

二、你提到的表格语法：XML注释中的Markdown嵌入 #

你记忆里的||__Column__|| || row ||是格式偏差，实际是Swashbuckle允许在XML注释中写入Markdown表格，正确的Markdown表格格式如下：

| 列标题1 | 列标题2 | 列标题3 |
|---------|---------|---------|
| 第一行值 | 第一行值 | 第一行值 |
| 第二行值 | 第二行值 | 第二行值 |

举个实际代码示例，你可以在<remarks>标签中这样使用：

/// <summary>
/// 获取系统角色列表
/// </summary>
/// <remarks>
/// 接口支持以下过滤参数：
/// | 参数名称 | 数据类型 | 是否必填 | 说明 |
/// |----------|----------|----------|------|
/// | roleName | string | 否 | 角色名称模糊匹配 |
/// | status | int | 否 | 角色状态（1=启用，0=禁用） |
/// </remarks>
/// <param name="query">查询参数</param>
/// <returns>角色列表数据</returns>
public IActionResult GetRoles(RoleQuery query)

这段代码中的Markdown表格，会在Swagger UI中自动渲染为美观的表格样式。

需要明确：这种用法是Swashbuckle专属的，通用XML注释本身不支持Markdown解析，是Swashbuckle为提升文档可读性专门添加的特性。

三、文档参考 #

Swashbuckle官方文档详细说明了XML注释的配置与Markdown支持的用法，你只需在项目启动时配置好Swashbuckle的XML文件路径，或启用注释解析功能，就能使用这些特性。

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