swagger-phpはクエリ文字列で配列を使用できますか？

Question

私はSwagger-phpを使用しています。クエリ文字列にあるパラメータを定義すると、配列になります。しかし、私は見ることができるものから、それはクエリ文字列のこの種類をサポートしていません：

https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12 

私は、可能な場合、これはin the collectionFormatfieldを設定すると考えています。現在はpipesを使用していますが、上記の形式を使用してSwagger-UIにこれも反映させたいと思います。しかし、私はthis github issueを読んでいますが、実際にこれが可能かどうか疑問に思っています。

私威張っ-PHPの定義の例：以下のJSONになり

/** 
*  @SWG\Parameter(
*   name="ids", 
*   in="query", 
*   description="A list of IDs (separated by pipes) to filter the Returns", 
*   required=false, 
*   type="array", 
*   @SWG\Items(
*    type="integer", 
*    format="int32" 
*  ), 
*   collectionFormat="pipes" 
* ) 
*/ 

：

"parameters": { 
    "ids": { 
     "name": "ids", 
     "in": "query", 
     "description": "A list of IDs (separated by pipes) to filter the Returns", 
     "required": false, 
     "type": "array", 
     "items": { 
      "type": "integer", 
      "format": "int32" 
     }, 
     "collectionFormat": "pipes" 
    } 
} 

Answer 1

は残念ながら、（あなたが提供する正確 URLを取得することはできませんhttps://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12）を使用します。

あなたは1次元配列のクエリパラメータを定義したいと仮定すると、（あなたが懸念多次元配列への参照のうえいるgithubの問題が）、ここでは現在のOpenAPIの（。FKA SWAGGER）仕様を提案することができるものです。

• あなたはpipesのようなコレクション形式で配列を使用する場合のURLは次のようになります（あなたはまた、別のセパレータを得るためにcsv、ssvまたはtsvを使用することができます）：

  https://api.domain.tld/v1/objects?q=1|5|12 
  

  これはあなたが探している構文ではありません。すべての配列項目は単一のqクエリパラメータで定義されています。

  https://api.domain.tld/v1/objects?q=1&q=5&q=12 
  

：

幸いなことに、別のコレクション形式あなたははほとんどあなたが欲しいものを得ることができ、この1で、独自のqパラメータで各配列の項目を定義することができmultiマイナス[]あり

この詳細については、OpenAPI (fka. Swagger) tutorial（開示：私が書いた）とspecification itself (ParameterObject description)

Answer 2

免責事項：私はSwaggerUIを使用していますが、これもあなたのために働くかもしれません。

私もしばらくの間、この疑問を抱いたが、私はjsのコードを通過し、私は変更することができるかどうかを確認/そこにそれを修正することを決めたと、私は、コードのこれらの数行に気づい：だから

if (type === 'brackets' || type === 'multi') { 
    var bracket = type === 'brackets' ? '[]' : '' 
    for (var i = 0; i < value.length; i++) { 
     if (i > 0) {encoded += '&';} 

     encoded += this.encodeQueryParam(name) + bracket + '=' + this.encodeQueryParam(value[i]); 
    } 
} 

をcollectionFormat「かっこ」がで、OpenAPI v2の仕様で定義されていないようです。それを試して、それは動作しているようだ。

Answer 3

/** 
*  @SWG\Parameter(
*   name="q[]", 
*   in="query", 
*   description="A list of IDs (separated by new lines) to filter the Returns", 
*   required=false, 
*   type="array", 
*   collectionFormat="multi", 
*   uniqueItems=true, 
* ) 
*/ 

これは感謝@Arnaudこの

{ 
    "name": "q[]", 
    "in": "query", 
    "description": "type", 
    "required": false, 
    "type": "array", 
    "collectionFormat": "multi", 
    "uniqueItems": true 
}