39

入力と出力の両方として、文字列キーでインデックス付けされたオブジェクトのマップを使用する API を Swagger で文書化する必要があります。

例：

{
    "a_property": {
        "foo": {
            "property_1": "a string 1",
            "property_2": "a string 2"
        },
        "bar": {
            "property_1": "a string 3",
            "property_2": "a string 4"
        }
    }
}

"foo" と "bar" は任意の文字列キーにすることができますが、一連のキーの中で一意である必要があります。

Swagger を使用してオブジェクトの配列を定義できることはわかっていますが、次のようなものがあるため、これは別の API を提供します。

{
    "a_property": [
        {
            "key": "foo"
            "property_1": "a string 1",
            "property_2": "a string 2"
        },
        {
            "key": "bar"
            "property_1": "a string 3",
            "property_2": "a string 4"
        }
    ]
}

「Open API 仕様」 - 「Map データ型のサポートの追加 #38」ページを読みました。私が理解している限り、additionalProperties を使用することをお勧めしますが、それは私のニーズに応えていないようです(または、私が使用している Swagger UI 2.1.4 では動作しません)。私は何か見落としてますか？

これまでのところ、次の回避策を見つけました(Swagger JSONで):

a_property: {
    description: "This is a map that can contain several objects indexed by different keys.",
    type: object,
    properties: {
        key: {
            description: "map item",
            type: "object",
            properties: {
                property_1: {
                    description: "first property",
                    type: string
                },
                property_2: {
                    description: "second property",
                    type: string
                }
            }
        }
    }
}

これでほぼ問題は解決しますが、読者は「キー」が任意の文字列であり、何度も繰り返される可能性があることを理解する必要があります。

必要なものを達成するためのより良い方法はありますか?

4

4 に答える 4

52

additionalPropertiesOpenAPI (fka.Swagger) 仕様で hashmap を記述するにはを使用するのが適切な方法ですが、Swagger UI は今のところそれらをレンダリングしません。

問題はここで追跡されますhttps://github.com/swagger-api/swagger-ui/issues/1248

その間、このトリックを使用できます:defaultマップのオブジェクトと同じタイプの必須ではないプロパティ (以下の例) を定義し、説明内にヒントを与えます。

swagger: "2.0"
info:
  version: 1.0.0
  title: Hashmap
  
paths: {}

definitions:
  MapItem:
    properties:
      firstname:
        type: string
      lastname:
        type: string
  Map:
    description: a (key, MapItem) map. `default`is an example key
    properties:
      default:
        $ref: '#/definitions/MapItem'
    additionalProperties:
      $ref: '#/definitions/MapItem'

この説明は、API コントラクトを変更せず、ドキュメントを改善します。

于 2016-05-16T16:03:18.883 に答える
5

私がそれを正しく理解していれば、基本的な問題は、特にキーが文字列よりも複雑な場合に、Java Map に対して広く受け入れられている JSON マッピングがないことです。私は、GSON が 1 つのアプローチを取る (キーをオブジェクトとして扱う) のに対し、Jackson は別のアプローチを取る (キーを文字列にシリアル化する) ことを見てきました。マップ (ディクショナリ) に相当する c# は、3 番目のアプローチを使用します (各エントリを、"Key" および "Value" と呼ばれるプロパティを持つ独自のキー値オブジェクトとして扱います)。Swagger は言語とシリアライザーにとらわれないようにしようとしているため、これは不可能な立場に置かれています。

于 2017-08-10T11:04:14.727 に答える
1

タイプをオブジェクトとして単純に使用できます。フロントエンドからのデータを解析しているとき、Map<Key,value> のようなものはありません。オブジェクトを送信しているだけです。マップはバックエンドのものまでです。そのため、オブジェクトを型として使用するよう求めています。オブジェクトでは、キーと値のペアを送信できます。以下の例のように

  metaData:
    type: object
    example: {
      "heading":"comfirmation email"
    }
于 2021-11-29T09:12:50.203 に答える