SwaggerUI 不为参数生成名称属性答案

【问题标题】：SwaggerUI not generating name attributes for parametersSwaggerUI 不为参数生成名称属性
【发布时间】：2018-06-01 21:57:56
【问题描述】：

我使用这个 PHP 包为我的 PHP REST API 创建了我的swagger.json： https://github.com/zircote/swagger-php

但是，当尝试从 Swagger UI 测试我的 API 时，由于某种原因，输入没有名称属性，我收到错误：
Notice: Undefined index: year 和 Notice: Undefined index: make

这是加载我的 swagger.json 时生成的 HTML：

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

任何想法如何解决这个问题？

【问题讨论】：

您在哪里看到这些错误？可以发截图吗？不过，它们不应该以任何方式影响“试用”功能（例如，petstore.swagger.io 也有没有名称的输入，并且“试用”可以正常工作。）
另外，注释也不太正确。由于您使用的是路径参数，因此端点应类似于 /API/GetModels/{year}/{make} 或 /API/GetModels/{make}/{year}。或者如果参数应该在查询字符串中传递，它们应该是in: query 而不是in: path。
我不知道in 属性的query 值。
@Helen，请发表您的评论作为答案。

标签： php swagger

【解决方案1】：

注释看起来不正确。

由于您使用的是in: path 参数，因此端点应类似于/API/GetModels/{year}/{make} 或/API/GetModels/{make}/{year}——也就是说，参数是URL 的一部分。

如果参数应该在查询字符串中传递，它们应该是in: query 而不是in: path。

要详细了解 OpenAPI/Swagger 中的各种参数类型，请参阅Describing Parameters。本指南解释了实际的 OpenAPI 语法而不是 Swagger-PHP 注释，但它应该可以帮助您理解。

【讨论】：