查询参数中传递的聚合对象的 Swagger 描述不起作用

Question

我正在 dotnet 中开发 GET API，并且一直在尝试记录传递的查询参数，该参数是用于结果分页（页面大小和页码）的聚合对象。 get 方法的评论/文档：

/// <param name="Id">ID used to identify a record</param>
/// <param name="paginationParams">Request object that contains the pagination parameters <inheritdoc cref="PaginationParameters"/></param>

正如您在上面所看到的，我指的是 PaginationParameters 聚合对象/模型。现在，这似乎无法正常工作，或者没有任何影响，因为我可以将该字段更改为 [Required]，然后 swagger 就会反映这一点。然而，值得注意的是 ID 字段记录良好。

下面是 get 方法的方法签名：

public async Task<IActionResult> GetStuff(
    [FromHeader][BindRequired] int Id, 
    [FromQuery] PaginationParameters paginationParams)

最后，我的模型如下：

/// <summary>
/// Pagination parameters 
/// </summary>

public class PaginationParameters
{   
    /// <summary>
    /// PageNumber
    /// </summary>
    [Required]
    public int? PageNumber { get; set; } = null;
    
    /// <summary>
    /// PageSize
    /// </summary>
    [Required]
    public int? PageSize { get; set; } = null;
}

它不起作用，这让我很烦恼，我确信这将是一个简单的修复，它似乎忽略了我对页面大小和页码的描述。

Answer 1

我也遇到了这个问题！

您需要确保您的 .csproj 文件正在生成文档：

<GenerateDocumentationFile>True</GenerateDocumentationFile>

然后，当您配置 Swagger 时，请确保使用 XML 注释引用对象的命名空间：

var filePath = Path.Combine(AppContext.BaseDirectory, "Your.Api.Namespace.xml");
c.IncludeXmlComments(filePath);

我的部分答案取自这里。