29

我正在努力使用 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

但这会产生： 大摇大摆的编辑器结果

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

4

3 回答 3

27

你的用法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为必需的键：

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 Editor中看起来很好。

Swagger 编辑器中的模型架构

于 2016-12-12T16:49:54.163 回答
15

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

  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 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
于 2016-12-12T18:39:42.130 回答
-1

如果您仍处于设计阶段，您可以将所有其他语言引用推送到具有如下结构的数组中，而不是使用动态键：

{
"launguage":"en"
"text":"Hello World"
}

这将大大简化事情，并且由于您不依赖 . additionalProperties，您生成的客户端库会发现这更容易消化。

于 2016-12-15T05:41:43.447 回答