OpenApi 注释导致双斜杠

Question

我正在使用 zircote/swagger-php 根据我添加到现有代码的 OpenApi 注释生成 API 文档。

在大多数情况下它工作正常，但我注意到一个奇怪的地方。我有一个方法 indexAction()，它应该 return 一个项目列表：

/**
 * @OA\Get(
 *      path="\location",
 *      description="Retrieves a list of locations for the current organisation",
 *      method="indexAction",
 *      @OA\Response(
 *          response="200",
 *          description="List of locations",
 *          @OA\JsonContent(
 *              type="array",
 *              @OA\Items(ref="#/components/schemas/Location")
 *          ),
 *          @OA\XmlContent(
 *              type="array",
 *              @OA\Items(ref="#/components/schemas/Location")
 *          )
 *      )
 * )
 */
public function indexAction()
{

编译文档json文件后，我打开它，这个动作如下：

"paths": {
    "\location": {
        "get": {
            "summary": "The index action handles index/list requests; it should respond with a\nlist of the requested resources.",
            "description": "Retrieves a list of locations for the current organisation",
            "operationId": "2b36ea7d6a6e350fd6c7564bc908a25b",
            "responses": {
                "200": {
                    "description": "List of locations",
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/Location"
                                }
                            }
                        },
                        "application/xml": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/Location"
                                }
                            }
                        }
                    }
                }
            }
        }
    },

出于某种原因，“路径”被列为 \location 而不是我所期望的 \location - 有人知道为什么会这样吗？我希望这就足够了，如果需要更多代码，我可以提供。

Answer 1

\ 只是 JSON 字符串中 \ 字符的转义版本。即"\location"字符串的实际值为\location.

但是，URL 路径使用 / 正斜杠，OpenAPI 也需要 paths start with /。所以你需要更换

path="\location",

和

path="/location",

OpenApi 注释导致双斜杠

OpenApi Annotations causing double slash

php

swagger

swagger-php

openapi

openapi-generator