具有动态键值哈希映射的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是正确的,您的模型是正确的.

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

这里也没有任何线索,结果将语言代码作为键,文本作为哈希映射的值.

这样的事情可以在口头记录description.

该示例似乎也没有按预期工作.它在UI中生成一个空的$ folded:.

不确定原始规格有什么问题,但上面的规范是有效的,并且在Swagger编辑器中看起来很好.

Answer 2

您似乎遇到了至少三个单独的错误和/或限制:

1. Swagger-Editor和Swagger-UI都没有在文档格式中提供任何指示,以显示additionalProperties对象模式中允许的内容.因此,即使您additionalProperties正确使用了它,并且Swagger解析器也能识别它,这些文档格式也不会显示它.您需要将此详细信息添加到架构中description,以便用户了解它们可以包含其他字符串属性.
   
   注意:您可能还希望其他属性名称遵循约定,例如双字母语言代码.虽然完整的JSON Schema允许您指定它patternProperties,但遗憾的是Swagger的架构对象不支持.同样,您应该在架构描述中指定它.

2. Swagger-Editor格式有时会显示这个奇怪的"折叠:"属性.我今天早上看到它,现在很奇怪我无法重现它.它今天可能已经固定好了.但无论如何,这肯定是一个错误,并且特定于Swagger-Editor.它不应该影响您的下游代码生成,也不应该影响在运行时向客户端开发人员提供API文档的标准Swagger-UI.(虽然Swagger-Editor中的文档窗格看起来与Swagger-UI类似,但它是一个单独的实现.)

3. additionalProperties在Swagger中使用有一些微妙但重要的限制.虽然Helen的示例没有显示任何可见的错误,但实际上Swagger解析器将无法正确处理此架构; 它会忽略你明确声明的en属性,或者会忽略additionalProperties!

最后一个问题归结为Swagger-Model中的设计缺陷,Swagger-Model是整个Swagger Java堆栈(包括Swagger-Codegen)中使用的核心组件之一.在某些情况下定义的模式可以组合工作properties和additionalProperties.但是在其他环境中定义的模式不能.

我们在这里详细记录了这一点.

好消息:通过小调整,我们可以让Helen的例子正常工作.我们只需要将嵌套对象模式提取到它自己的顶级定义中.我会称之为LocalizedName:

definitions:
  delayReason:
    type: object
    properties:
      id:
        type: string
        description: Identifier for a delay reason.
      name:
        $ref: "#/definitions/LocalizedName"
    required: [id, name]
    example:
      id: '123' # Note the quotes to force the value as a string
      name: 
        en: English text
        de: Deutscher Text

  LocalizedName:
    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