Могу ли я сделать использование 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"
    }
}
Источник

4 ответа

Решение

К сожалению, невозможно получить именно тот 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)

Источник 
/**
 *     @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
}

Результирующее изображение

Источник

Если вы еще этого не сделали, я предлагаю попробовать следующее:

*      @OA\Parameter(
*          name="category[]",
*          description="array of category numbers",
*          in="query",     
*          @OA\Schema( 
*              type="array", 
*              @OA\Items(type="enum", enum={1,2,3,4,5,6,7,8,9}),
*              example={1,2} 
*          )
*      ),

Я изменил это, чтобы соответствовать моему варианту использования:

*    @OA\Parameter(
*      name="things[]",
*      in="query",
*      description="A list of things.",
*      required=false,
*      @OA\Schema(
*        type="array",
*        @OA\Items(type="integer")
*      )
*    ),

Источник: https://github.com/zircote/swagger-php/issues/612

Источник

Теперь это можно сделать без [] взлома наиболее понравившегося ответа. Используйте стиль deepObject.

 name: q
 style: deepObject
 schema:
   type: array
   items:
     type: string

Будет создан URL-адрес следующего вида: q[0]=string1&q[1]=string2

Источник

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

 /**
 *     @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,
 *     )
 */
Источник

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

Источник

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

"параметры": [

      {

        "name": "fav",

        "description": "Enter ids of Favoruite",

        "in": "formData",

        "type": "array",

        "items": {

          "type": "integer",

          "format": "int32"

        },

        "paramType": "form",

        "required": true

      }],'
Источник
Другие вопросы по тегам