SwaggerUI не генерирует атрибуты имени для параметров

Question

Я создал swagger.json для моего PHP REST API с помощью этого пакета PHP: https://github.com/zircote/swagger-php

Однако при попытке протестировать мой API из интерфейса Swagger по какой-то причине входные данные НЕ ИМЕЮТАтрибут имени и я получаю ошибки:
Notice: Undefined index: year и Notice: Undefined index: make

Это сгенерированный HTML при загрузке моего swagger.json:

<tbody>
    <tr class="parameters">
        <td class="col parameters-col_name">
            <div class="parameter__name required">
                <!-- react-text: 360 -->year<!-- /react-text -->
                <span style="color: red;">&nbsp;*</span>
            </div>
            <div class="parameter__type">
                <!-- react-text: 363 -->integer<!-- /react-text -->
                <span class="prop-format">
                    <!-- react-text: 365 -->($<!-- /react-text -->
                    <!-- react-text: 366 -->int32<!-- /react-text -->
                    <!-- react-text: 367 -->)<!-- /react-text -->
                </span>
            </div>
            <div class="parameter__deprecated"></div>
            <div class="parameter__in">
                <!-- react-text: 370 -->(<!-- /react-text -->
                <!-- react-text: 371 -->path<!-- /react-text -->
                <!-- react-text: 372 -->)<!-- /react-text -->
            </div>
        </td>
        <td class="col parameters-col_description">
            <div class="markdown">year to retrieve models for</div>
            <input type="text" class="" title="" placeholder="year - year to retrieve models for" value="">
        </td>
    </tr>
    <tr class="parameters">
        <td class="col parameters-col_name">
            <div class="parameter__name required">
            <!-- react-text: 378 -->make<!-- /react-text -->
            <span style="color: red;">&nbsp;*</span>
            </div>
            <div class="parameter__type">
            <!-- react-text: 381 -->string<!-- /react-text -->
            </div>
            <div class="parameter__deprecated"></div>
            <div class="parameter__in">
            <!-- react-text: 384 -->(<!-- /react-text -->
            <!-- react-text: 385 -->path<!-- /react-text -->
            <!-- react-text: 386 -->)<!-- /react-text -->
            </div>
        </td>
        <td class="col parameters-col_description">
            <div class="markdown">make to retrieve models for</div>
            <input type="text" class="" title="" placeholder="make - make to retrieve models for" value="">
        </td>
    </tr>
</tbody>

А вот соответствующий раздел моего swagger.json:

"/API/GetModels": {
    "get": {
        "summary": "Get Available Models",
        "description": "Gets Models available for passed year/make combination",
        "produces": [
            "application/json"
        ],
        "parameters": [
            {
                "name": "year",
                "in": "path",
                "description": "year to retrieve models for",
                "required": true,
                "type": "integer",
                "format": "int32"
            },
            {
                "name": "make",
                "in": "path",
                "description": "make to retrieve models for",
                "required": true,
                "type": "string"
            }
        ],
        "responses": {
            "200": {
                "description": "successful operation"
            },
            "500": {
                "description": "Internal error"
            }
        }
    }
},

Вот мои аннотации в моем PHP-скрипте:

/**
 *
 * @SWG\Get(path="/API/GetModels",
 *   description="Gets Models available for passed year/make combination",
 *   produces={"application/json"},
 *   summary="Get Available Models", 
 *   @SWG\Parameter(
 *      name="year",
 *      in="path",
 *      type="integer",
 *      format="int32",
 *      description="year to retrieve models for",
 *      required=true,
 *   ),
 *   @SWG\Parameter(
 *      name="make",
 *      in="path",
 *      type="string",
 *      description="make to retrieve models for",
 *      required=true,
 *   ),
 *   @SWG\Response(response=200,description="successful operation"),
 *   @SWG\Response(response=500,description="Internal error")
 *   )
 * )
 */

Есть идеи как это исправить?

Answer 1

Аннотации выглядят неправильно.

Поскольку вы используете in: path параметры, конечная точка должна выглядеть как /API/GetModels/{year}/{make} или /API/GetModels/{make}/{year} - то есть параметры являются частью URL.

Если предполагается, что параметры передаются в строке запроса, они должны быть in: query, а не in: path.

Чтобы узнать больше о различных типах параметров в OpenAPI / Swagger, см. Описание параметров .В этом руководстве объясняется фактический синтаксис OpenAPI, а не аннотации Swagger-PHP, но это должно помочь вам понять.