Kann ich Swagger-PHP Arrays in der Abfragezeichenfolge verwenden?

Question

Ich benutze Swagger-php. Wenn ich einen Parameter definiere, der in der Abfragekette steht, kann es ein Array sein. Aber von dem, was ich sehen kann, ist es nicht diese Art von Abfragezeichenfolgeflag unterstützen:

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

Ich glaube, dies würde in the collectionFormatfield wenn möglich eingestellt werden. Derzeit habe ich gerade pipes verwendet, aber ich möchte das obige Format verwenden, und haben Swagger-UI dies auch widerspiegeln. Allerdings habe ich this github issue gelesen, was mich dazu gebracht hat, mich zu fragen, ob das tatsächlich möglich ist und ich es gerade verpasst habe?

Ein Beispiel für meine Swagger-PHP-Definition:

/** 
*  @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" 
* ) 
*/ 

die in den folgenden JSON-Ergebnisse:

"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

Leider ist es nicht möglich, genau die URL, die Sie zur Verfügung stellen zu erhalten (https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12) für einen Array-Abfrageparameter.

Unter der Annahme, dass Sie einen 1 Dimension Array Abfrageparameter definieren wollen (die Github Problem Sie beziehen Bedenken multidimensionalen Arrays), hier ist es, was die aktuelle OpenAPI (fka Swagger.) Spezifikation vorschlagen:

• Wenn Sie ein Array mit einer Sammlung Format wie pipes verwenden (Sie können auch csv verwenden können, ssv oder tsv an verschiedene Separatoren zu erhalten) die URL wie folgt aussehen:

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

  Dies ist jedoch nicht die von Ihnen gesuchte Syntax: Alle Array-Elemente sind in einem einzelnen q Abfrageparameter definiert.

• Glücklicherweise gibt es eine weitere Sammlung Format multi so dass jedes Array Stück in seinem eigenen q Parameter definieren, mit diesem kann man fast bekommen, was Sie wollen, abzüglich der []:

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

Sie können mehr darüber in dieser OpenAPI (fka. Swagger) tutorial lesen (Offenlegung: ich schrieb es) und in der specification itself (ParameterObject description)

Answer 2

Haftungsausschluss: Ich benutze SwaggerUI, aber das könnte auch für Sie arbeiten.

ich auch darüber fragen, für einige Zeit war, aber ich beschlossen, durch den js Code gehen und sehen, ob ich es dort ändern kann/fix und bemerkte ich diese paar Zeilen Code: So

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]); 
    } 
} 

es scheint, dass es ein collectionFormat 'Klammern', die nicht in der OpenAPI v2 Spezifikation definiert wurde. Versuchte es und es scheint zu funktionieren.

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, 
* ) 
*/ 

Diese similiar in etwas führt zu diesem

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