Можно ли сделать так, чтобы swagger-php использовал массивы в строке запроса?

Question

Можно ли сделать так, чтобы swagger-php использовал массивы в строке запроса?

Я использую Swagger-php. Когда я определяю параметр в строке запроса, это может быть массив. Но из того, что я вижу, он не поддерживает этот вид строки запроса:

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

Я верю, что это будет установлено в collectionFormatполе если возможно. В настоящее время я просто использую pipes, но я хочу использовать вышеупомянутый формат, и у Swagger-UI это тоже отражается. Тем не менее, я прочитал этот вопрос GitHub что заставило меня задуматься, возможно ли это на самом деле, и я просто пропустил это?

Пример моего определения Swagger-PHP:

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

Что приводит к следующему JSON:

"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"}
}

3

php swagger swagger-php swagger-ui

Решение

Другие решения

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

Это приведет к чему-то похожему на это

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

6

Отказ от ответственности: я использую 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 Спецификация. Пробовал, и, кажется, работает.

0

Пожалуйста, пройдите это; это работа для меня

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

0

Следующий код работает нормально: Смотрите скриншот

«параметры»: [

      {

"name": "fav",

"description": "Enter ids of Favoruite",

"in": "formData",

"type": "array",

"items": {

"type": "integer",

"format": "int32"
},

"paramType": "form",

"required": true

}],'

0

Источник

Accepted Answer

К сожалению, это не возможно получить именно так URL, который вы предоставляете (https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12) для параметра запроса массива.

Предполагая, что вы хотите определить параметр запроса 1-мерного массива (проблема github, к которой вы обращаетесь, относится к многомерным массивам), вот что может предложить текущая Спецификация OpenAPI (fka. Swagger):

Если вы используете массив с форматом коллекции, как pipes (вы также можете использовать csv, ssv или же tsv чтобы получить разные разделители) URL будет выглядеть так:
```
https://api.domain.tld/v1/objects?q=1|5|12
```
Но это не тот синтаксис, который вы ищете: все элементы массива определены в одном q параметр запроса.
К счастью, есть другой формат коллекции multi позволяя определить элемент каждого массива по-своему q параметр, с этим вы можете почти получить то, что вы хотите минус []:
```
https://api.domain.tld/v1/objects?q=1&q=5&q=12
```

Вы можете прочитать больше об этом в этом OpenAPI (fka. Swagger) учебник (раскрытие: я написал это) и в сама спецификация (описание ParameterObject)

0