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

しかし、これは以下を生成します: swagger エディターの結果

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

4

3 に答える 3

15

少なくとも 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. additionalPropertiesSwaggerでの の使用には、微妙ではあるが重大な制限がいくつかあります。Helenの例では目に見えるエラーは示されていませんが、実際には Swagger パーサーはこのスキーマを正しく処理できません。明示的に宣言されたenプロパティを無視するか、無視しますadditionalProperties!

この最後の問題は、Swagger Java スタック (Swagger-Codegen を含む) 全体で使用されるコア コンポーネントの 1 つである Swagger-Model の設計上の欠陥に帰着します。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 に答える