使用 Swashbuckle AspNetCore 生成的 UI 文档不支持 JsonProperty 值

Question

我创建了一个 class，我想将其用于发送排序和分页信息以应用于我的大型 collections。我有一个 .NET Core Web API 服务，它将接收请求并将我的 object 作为输入 FromQuery。我想为参数名称遵守某些命名约定（即 Microsoft Rest API Guidelines），例如 $orderby、$top、$skip 等，并注释了 class 使用 JsonProperty。

但是，在生成的 swagger 文档中，这些只是显示为属性名称本身，这在我的属性被命名为 Take 的情况下是一个问题，例如请求参数应该是$top。我希望生成的文档能够匹配，不会对 API 的消费者造成任何混淆。我读到的所有内容似乎都表明这应该有效，但我很困惑为什么它不适合我。

这是我的 class，注释使用 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，如所述 Override Schema for Specific Types 但运气不好。感谢任何人对此提供的任何见解。

Answer 1

根据 this GitHub issue，JsonSerializer 不用于绑定到 GET 请求的 class。您需要改为自定义模型绑定。

So, when you use a class to represent query parameters, the JsonSerializer isn’t involved. Instead, MVC model binding is used to assign values directly from the request into the instance properties.

So, if you want to be explicit about required casing for this behavior, and hence the generated description, you need to customize the model binding behavior too. I’m not at my laptop now but off the top of my head, I think you can annotate properties with “FromQuery” and set the bind name that way.

如果我正确理解 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; }
}

使用 Swashbuckle AspNetCore 生成的 UI 文档不支持 JsonProperty 值

Generated UI doc not honoring JsonProperty value using Swashbuckle AspNetCore

c#

swagger

swagger-ui

swashbuckle

asp.net-core-webapi