使用 Swashbuckle AspNetCore 生成的 UI 文档不尊重 JsonProperty 值

Question

我创建了一个类，我想用它来发送排序和分页信息以应用于我的大型集合。我有一个 .NET Core Web API 服务，它将接收请求并将我的对象作为输入FromQuery。我想坚持一定的命名约定（即微软的REST API准则）为参数名这样的$orderby，$top，$skip等，都注解使用类的属性JsonProperty。

但是，在生成的 swagger 文档中，这些只是显示为属性名称本身，这在我的属性被命名Take但请求参数应该是$top. 我希望生成的文档匹配，以免给 API 的使用者造成任何混淆。我读到的一切似乎都表明这应该有效，我很难过为什么它不适合我。

这是我使用的带有注释的类 Newtonsoft.Json.JsonPropertyAttribute

[JsonObject]
public class QueryParams {

    [JsonProperty( "$orderBy" )]
    public string OrderBy { get; set; }

    [JsonProperty( "$skip" )]
    public int? Skip { get; set; }

    [JsonProperty( "$top" )]
    public int? Take { get; set; }

    [JsonProperty( "$maxpagesize" )]
    public int? MaxPageSize { get; set; }

    [JsonProperty( "$count" )]
    public bool? IncludeCount { get; set; }
}

然后例如我的 Web API 操作方法看起来像这样

    [HttpGet( "type/{type}" )]
    public async Task<IActionResult> GetByType( 
        string type, 
        [FromQuery]QueryParams parameters ) 
    {
       /* ... */ 

    }

我曾尝试一些东西，如欲以MapType截至指出 覆盖模式为特定类型的，但就是不存有任何侥幸。感谢任何人可以就此提供的任何见解。

Answer 1

根据此 GitHub 问题，JsonSerializer不用于绑定到 GET 请求的类。您需要改为自定义模型绑定。

因此，当您使用类来表示查询参数时，不涉及 JsonSerializer。相反，MVC 模型绑定用于将值直接从请求分配到实例属性中。

因此，如果您想明确说明此行为所需的大小写以及生成的描述，您还需要自定义模型绑定行为。我现在不在我的笔记本电脑旁，而是在我的头顶上，我认为您可以使用“FromQuery”注释属性并以这种方式设置绑定名称。

如果我正确理解 GH 问题中的讨论，以下应该有效：

public class QueryParams {

    [FromQuery( Name = "$orderBy" )]
    public string OrderBy { get; set; }

    [FromQuery( Name = "$skip" )]
    public int? Skip { get; set; }

    [FromQuery( Name = "$top" )]
    public int? Take { get; set; }

    [FromQuery( Name = "$maxpagesize" )]
    public int? MaxPageSize { get; set; }

    [FromQuery( Name = "$count" )]
    public bool? IncludeCount { get; set; }
}