Swagger 在 ASP.CORE 3 中为字典生成不正确的 URL [英] Swagger generates incorrect URL for dictionary in ASP.CORE 3

问题描述

当从查询字符串中提取的模型具有字典作为其属性之一时，Swagger 会生成错误的 URL.如何告诉 Swagger 更改 URL 中字典的格式或手动定义输入参数模式，而不自动生成?尝试使用 Swashbuckle 和 NSwag.

Swagger generates incorrect URL when model extracted from query string has a dictionary as one of its properties. How to tell Swagger to change format of the dictionary in the URL or to define input parameters schema manually, without auto-generation? Tried to use Swashbuckle and NSwag.

控制器

public class RecordsController : ControllerBase
{
  [HttpGet]
  [Route("services/records")]
  public async Task<IActionResult> Records([FromQuery] QueryModel queryModel)
  {
    return null;
  }
}

输入模型 - 查询字符串

public class QueryModel 
{
  public int Page { get; set; }
  public int Count { get; set; }
  public Dictionary<Columns, string> Conditions { get; set; }
}

Swagger UI 显示查询模型上条件"属性的这种格式

Swagger UI shows this format for "Conditions" property on Query Model

{
  "UserId": "string",
  "GroupId": "string",
  "RecordId": "string"
}

Swagger 生成的 URL - Open API v2 - 不会绑定到条件"

Swagger generated URL - Open API v2 - will not be bound to "Conditions"

/services/records?Page=0&Count=5&Conditions={"UserId":"1"} 

Swagger 生成的 URL - Open API v3 - 不会绑定到条件"

Swagger generated URL - Open API v3 - will not be bound to "Conditions"

/services/records?Page=0&Count=5&UserId=1 

自定义 URL - 按预期工作并使用 { "UserId", "1" }

Custom URL - works as expected and initializes "Conditions" with { "UserId", "1" }

/services/records?Page=0&Count=5&Conditions[UserId]=1 

问题

如何强制 Swagger 为 Dictionary 类型的属性呈现类似 PropertyName[Key]=Value 的 URL?

How to enforce Swagger to render URL like PropertyName[Key]=Value for the property of type Dictionary?

备选问题

不是解决方案，但如果我以这种方式为输入参数定义默认值，Swagger 会创建正确的 URL.

Not a solution, but if I define default value for my input parameter this way, Swagger creates correct URL.

{
  "Conditions[UserId]": "1",
  "Conditions[GroupId]": "2"
}

URL 现在正确并且正确绑定到模型

URL is correct now and is properly bound to the model

/services/records?Page=0&Count=5&Conditions[UserId]=1&Conditions[GroupId]=2 

有没有办法更改 Swagger 中为 Dictionary 输入类型显示的默认值?

Is there a way to change default value displayed in Swagger for Dictionary input type?

推荐答案

您需要为查询定义设置查询样式deepObject

You will need to set the query style deepObject for the query definition

NSwag 目前通过 SwaggerParameterStyle 您将为其设置值 deepObject.

This is currently supported by NSwag through SwaggerParameterStyle for which you will set value deepObject.

我也很好奇如何在没有 NSwag 的情况下做到这一点，所以我看了一下 https://editor.swagger.io/

I was also curious how to do this without NSwag, so I took a look at https://editor.swagger.io/

在这里，您可以为它提供静态 json 招摇，如果您想查看创建相同设置的不同方式，它将为您生成服务器

Here you can provide it your static json swagger and it will generate you a server if you want to see a different way of creating the same setup

字典样本模型

[DataContract]
public partial class Dictionary : IEquatable<Dictionary>
{ 
    /// <summary>
    /// Gets or Sets Word
    /// </summary>
    [DataMember(Name="word")]
    public string Word { get; set; }

    /// <summary>
    /// Gets or Sets Define
    /// </summary>
    [DataMember(Name="define")]
    public string Define { get; set; }

样品控制器

    /// <summary>
    /// Get word definition
    /// </summary>
    /// <remarks>Get me the word definitions</remarks>
    /// <param name="dictionary">Status values that need to be considered for filter</param>
    /// <response code="200">successful operation</response>
    [HttpGet]
    [Route("/v2/book")]
    [ValidateModelState]
    [SwaggerOperation("BookGet")]
    public virtual IActionResult BookGet([FromQuery][Required()]Dictionary dictionary)

原始 Swagger 示例查询

Raw Swagger example query

/book:
  get:
    summary: Get word definition
    description: Get me the word definitions
    parameters:
    - name: dictionary
      in: query
      description: Status values that need to be considered for filter
      required: true
      style: deepObject
      schema:
        type: object
        properties:
          word: 
            type: string
          define:
            type: string

查看 https://swagger.io/specification/

这篇关于Swagger 在 ASP.CORE 3 中为字典生成不正确的 URL的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！