具有动态键值哈希映射的Swagger复杂响应模型 [英] Swagger complex response model with dynamic key value hash maps

问题描述

我正忙于使用swagger的语法来描述响应类型。我试图建模的是具有动态键和值的哈希映射。这是需要进行本地化的。这些语言可能会有所不同，但应始终提供英语。

响应在JSON中看起来像这样：

  {
 id：1234，
 name：{
 en：english text，
 de：Deutscher Text
} 
} 
  

我的第一次尝试是这样的，但我没有想法如何写名字的部分。 AdditionalProperties似乎是一个关键，但我无法将它包裹在头上。在这个语法中对英文文本的要求也是一个谜，而且这个例子似乎也没有像预期的那样工作。

  delayReason：
类型：对象
属性： 
 id：
类型：字符串
描述：延迟原因的标识符。 
名称：
类型：对象
 additionalProperties：
类型：字符串
必需：[id，name] 
示例：
 id：123 
名称：
 en：英文文本
 de：Deutscher Text 
  

但是这会产生：

也没有线索，结果将会有一个语言代码为一个关键字和文本作为哈希映射的值。

解决方案

看来您至少遇到三个单独的错误， /或限制：

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




2. Swagger-Editor格式有时会显示这个奇怪的折叠：属性。我今天早上看到它，现在奇怪我无法再现它。它今天可能已被固定。但无论如何，这当然是一个错误，并且特定于Swagger-Editor。它不应该影响您的下游代码生成，也不会影响在运行时向客户端开发人员呈现API文档的标准Swagger-UI。 （尽管Swagger-Editor中的文档窗格与Swagger-UI类似，但它是一个单独的实现。）

在Swagger中使用 additionalProperties 。虽然 Helen 的示例没有显示任何可见的错误，但事实上，Swagger解析器将无法正确处理此架构;它会忽略显式声明的 en 属性，或者忽略 additionalProperties ！

最后一个问题归结为Swagger-Model中的一个设计缺陷，Swagger模型是整个Swagger中使用的核心组件之一Java堆栈（包括Swagger-Codegen）。在特定上下文中定义的模式可以使用属性和 additionalProperties 的组合。但是在其他上下文中定义的模式不能。

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

好消息：通过小小的调整，我们可以制作海伦的例子正确地工作。我们只需要将嵌套对象模式提取到它自己的顶级定义中。我将它称为 LocalizedName ：

 定义：
 delayReason：
类型：对象
属性：
 id：
类型：字符串
描述：延迟原因的标识符。 
名称：
 $ ref：＃/ definitions / LocalizedName
 required：[id，name] 
示例：
 id：'123'＃注意引号强制将该值作为字符串
名称：
 en：英语文本
 de：Deutscher文本
 
本地化名称：
类型：对象
描述：以语言代码作为键和文本作为值的散列表。 
属性：
 en：
类型：字符串
描述：延迟原因的英文文本。 
 required：[en] 
 additionalProperties：
 type：string 
  

I'm struggling with the syntax of swagger to describe a response type. What I'm trying to model is a hash map with dynamic keys and values. This is needed to allow a localization. The languages may vary, but english should always be provided.

The response would look like this in JSON:

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

My first try was looking like that, but I have no idea how to write the part for the name. AdditionalProperties seems to be a key, but I can't wrap my head around it. Also the requirement for english text is a mystery to me in this syntax and the example also does not seem to work as expected. It generates an empty $folded: in the UI.

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

But this produces:

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.

解决方案

It seems you are running into at least three separate bugs and/or limitations:

1. Neither Swagger-Editor nor Swagger-UI provide any indication in the documentation format to show that additionalProperties are allowed in your object schema. So even where you've used additionalProperties correctly, and it's recognized by the Swagger parser, these documentation formats won't show it. You need to add this detail to your schema description, so users understand that they can include additional string properties.
   
   Note: You probably also expect the additional property names to follow a convention, e.g. a two-letter language code. While full JSON Schema lets you specify this with patternProperties, unfortunately that's not supported in Swagger's schema object. So again, you should specify that in your schema description.

2. The Swagger-Editor format sometimes shows this odd "folded:" property. I saw it this morning, now strangely I cannot reproduce it. It might have been hotfixed today. But regardless, it's certainly a bug, and specific to Swagger-Editor. It should not affect your downstream code generation, nor the standard Swagger-UI that presents your API documentation to client developers at runtime. (Though the documentation pane in Swagger-Editor looks similar to Swagger-UI, it is a separate implementation.)

3. There are some subtle but significant limitations to the use of additionalProperties in Swagger. While Helen's example doesn't show any visible errors, in fact the Swagger parser will fail to process this schema correctly; it will ignore either your explicitly declared en property, or will ignore additionalProperties!

This last issue comes down to a design flaw in Swagger-Model, one of the core components used throughout the Swagger Java stack (including Swagger-Codegen). Schemas defined in certain contexts can work with a combination of properties and additionalProperties. But schemas defined in other contexts cannot.

We've documented this in detail here.

The good news: with a small tweak, we can make Helen's example work correctly. We just need to extract the nested object schema into its own top-level definition. I'll call it 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

这篇关于具有动态键值哈希映射的Swagger复杂响应模型的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！