.NET中Swagger无法显示Query参数聚合对象的描述信息

问题分析 #

你用<inheritdoc cref="PaginationParameters"/>在API方法的参数注释中引用分页模型，但Swagger无法解析这种跨元素的注释继承，且默认不会自动关联[FromQuery]复杂类型的属性注释，导致仅能识别[Required]特性，看不到PageNumber和PageSize的描述。

修复方案 #

1. 确保生成并加载所有XML注释文件

Swagger依赖XML注释文件读取类和属性的描述，需要同时开启API项目和模型项目的XML文档生成：

• 右键对应项目 → 属性 → 生成 → 勾选「XML文档文件」，记下生成路径（通常在bin/Debug/[.NET版本]/目录下）。
• 在Program.cs的Swagger配置中加载这些XML文件：

builder.Services.AddSwaggerGen(c =>
{
    // 加载API项目的XML注释
    var apiXmlPath = Path.Combine(AppContext.BaseDirectory, "YourApiProject.xml");
    c.IncludeXmlComments(apiXmlPath);

    // 加载包含PaginationParameters的模型项目XML注释
    var modelXmlPath = Path.Combine(AppContext.BaseDirectory, "YourModelProject.xml");
    c.IncludeXmlComments(modelXmlPath);
});

2. 简化参数注释，移除

不需要通过<inheritdoc>引用模型注释，直接简化GetStuff方法的参数注释：

/// <param name="Id">ID used to identify a record</param>
/// <param name="paginationParams">分页参数（包含页码和页大小）</param>

Swashbuckle会自动读取PaginationParameters类及其属性的XML注释，将PageNumber和PageSize拆分为独立的Query参数，并展示各自的描述和[Required]标记。

3. （可选）升级Swashbuckle.AspNetCore版本

如果上述操作无效，可能是版本兼容问题，升级到最新稳定版的Swashbuckle.AspNetCore NuGet包，确保对复杂类型Query参数的注释支持更完善。

验证 #

重启API后查看Swagger文档，PageNumber和PageSize参数会显示各自的<summary>注释内容，同时保留必填标记。

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