具有动态键值哈希映射的Swagger复杂响应模型

Question

我正在努力使用swagger的语法来描述响应类型。我试图建模的是一个带有动态键和值的哈希映射。这是允许本地化所必需的。语言可能不同，但应始终提供英语。

在JSON中，响应如下所示：

{
  id: "1234",
  name: {
    en: "english text",
    de: "Deutscher Text"
  }
}

我的第一次尝试是这样的，但我不知道如何为这个名字写部分。AdditionalProperties似乎是一把钥匙，但我无法把头缠在它身上。另外，对英语文本的要求对我来说是一个谜，在这个语法中，这个例子似乎也不像预期的那样工作。它在UI中生成一个空的$folded:。

delayReason:
  type: object
  properties:
    id:
      type: string
      description: Identifier for a delay reason.
    name:
      type: object
      additionalProperties: 
        type: string
  required: [id, name]
  example:
    id: 123
    name: 
      en: english text
      de: Deutscher Text

这也没有线索表明结果将有一个语言代码作为键，而文本作为散列映射的值。

Answer 1

AdditionalProperties的用法是正确的，模型也是正确的。

在Swagger/OpenAPI中，hashmap键被假定为字符串，因此键类型没有显式定义。AdditionalProperties定义hashmap值的类型。所以，这个模式

type: object
additionalProperties: 
  type: string

定义字符串到字符串的映射，例如：

{
  "en": "English text",
  "de": "Deutscher Text"
}

如果需要字符串到整数的映射，例如：

{
  "en": 5,
  "de": 3
}

您可以将additionalproperties定义为具有值类型integer:

type: object
additionalProperties: 
  type: integer

将en定义为HashMap中的必需键：

type: object
properties:
  en:
    type: string
required: [en]
additionalProperties: 
  type: string

definitions:
  delayReason:
    type: object
    properties:
      id:
        type: string
        description: Identifier for a delay reason.
      name:
        type: object
        description: A hashmap with language code as a key and the text as the value.
        properties:
          en:
            type: string
            description: English text of a delay reason.
        required: [en]
        additionalProperties: 
          type: string
    required: [id, name]
    example:
      id: '123' # Note the quotes to force the value as a string
      name: 
        en: English text
        de: Deutscher Text

这也没有线索表明结果将有一个语言代码作为键，而文本作为散列映射的值。

类似的事情可以在描述中口头记录。

这个例子似乎也没有达到预期的效果。它在UI中生成一个空的$folded:。

不确定您的原始规范有什么问题，但上面的规范是有效的，在Swagger编辑器中看起来很好。