web-dev-qa-db-ja.com

動的なキー値ハッシュマップを使用した複雑な応答モデルの変更

私は、応答タイプを記述するために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

しかし、これは以下を生成します： swagger editor result

これには、結果がキーとして言語コードを持ち、ハッシュマップの値としてテキストを持つという手掛かりもありません。

hashmapswaggerswagger-2.0swagger-editor
15
user1736217

少なくとも3つの個別のバグや制限に直面しているようです。

  1. Swagger-EditorもSwagger-UIも、additionalPropertiesがオブジェクトスキーマで許可されていることを示すドキュメント形式の表示を提供しません。したがって、additionalPropertiesを正しく使用し、Swaggerパーサーによって認識された場合でも、これらのドキュメント形式では表示されません。この詳細をスキーマdescriptionに追加する必要があるため、ユーザーは追加の文字列プロパティを含めることができることを理解します。

    注：追加のプロパティ名は、慣例に従うことを期待するでしょう。 2文字の言語コード。完全なJSONスキーマではpatternPropertiesでこれを指定できますが、残念ながらSwaggerのスキーマオブジェクトではサポートされていません。そのため、スキーマの説明でそれを指定する必要があります。

  2. Swagger-Editor形式では、この奇妙な「folded：」プロパティが表示される場合があります。今朝見ましたが、今では奇妙に再現できません。今日は修正プログラムが適用された可能性があります。ただし、それは確かにバグであり、Swagger-Editorに固有のものです。ダウンストリームのコード生成や、実行時にクライアント開発者にAPIドキュメントを提示する標準のSwagger-UIに影響することはありません。 （Swagger-EditorのドキュメントペインはSwagger-UIに似ていますが、別個の実装です。）

  3. SwaggerでのadditionalPropertiesの使用には、わずかではありますが重要な制限があります。 Helen の例では目に見えるエラーは表示されませんが、実際にはSwaggerパーサーはこのスキーマを正しく処理できません。明示的に宣言されたenプロパティを無視するか、additionalProperties！を無視します。

この最後の問題は、Swagger Javaスタック（Swagger-Codegenを含む）全体で使用されるコアコンポーネントの1つです。特定のコンテキストで定義されたスキーマが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
12
Ted Epstein

additionalPropertiesの使用は正しく、モデルは正しいです。

additionalProperties

Swagger/OpenAPIでは、ハッシュマップキーは文字列であると想定されているため、キータイプは明示的に定義されていません。 additionalPropertiesは、ハッシュマップ値のタイプを定義します。したがって、このスキーマ

type: object
additionalProperties: 
  type: string

次のような文字列から文字列へのマップを定義します。

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

次のような文字列から整数へのマップが必要な場合：

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

additionalPropertiesを値型integerとして定義します：

type: object
additionalProperties: 
  type: integer

ハッシュマップの必須キー

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 で正常に見えます。

Model schema in Swagger Editor

18
Helen

ダイナミックキーを使用する代わりに、まだ設計段階にいる場合は、次のような構造を持つ配列内の他のすべての言語参照をプッシュできます。

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

それは物事を非常に単純化し、additionalPropertiesに依存していないので、生成されたクライアントライブラリはこれを消化するのがより簡単だとわかります。

0
Sanket Berde