hashmap - 具有动态键值 HashMap 的 Swagger 复杂响应模型

Question

我正在努力使用 swagger 的语法来描述响应类型。我想要建模的是具有动态键和值的 HashMap 。这是允许本地化所必需的。语言可能有所不同，但应始终提供英语。

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

但这会产生:

也没有任何线索表明结果将以语言代码作为键，以文本作为 HashMap 的值。

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

HashMap 中所需的键

将 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

There is also no clue in this that the result will have a language code as a key and the text as the value of the hash map.

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

the example also does not seem to work as expected. It generates an empty $folded: in the UI.

不确定您的原始规范有什么问题，但上面的规范是有效的，并且在 Swagger Editor 中看起来很好.