Swagger API 文档：“无法解析参考：针对意外元素评估令牌“路径”时 JSONPointer 评估失败”

Question

我正在开发一个包含 API 的项目。 我目前正在尝试使用 Swagger 记录 API。

我想为我的路由使用外部路径，以避免 yaml 中的行数超过 2000 行。 但是我似乎无法为我的路线使用外部路径，它说找不到#paths。

我有一个 global.yaml，其中包含基本 API 文档，以及不同路由的路径

openapi: "3.1.0"
info:
  title: "blabla"
  version: "0.1.0"
  description: "This is a simple CRUD API application made with Express documented with Swagger"
  license:
    name: "MIT"
    url: "https://spdx.org/licenses/MIT.html"
  contact:
    name: "me"
    url: "me.com"
    email: "[email protected]"
servers:
  - url: "http://localhost:8080"
paths:
  /api/youtube/youtubeWebhook:
    $ref: './youtube.yaml#/paths/~1youtubeWebhook' # <- this doesn't work
... more paths to come
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API token obtained from the login or register route

我也想避免一一定义每条路线，但显然不可能使用 1 个 yaml 引用整个路线（/api/youtube），所以现在就这样做。

我的 youtube.yaml 位于同一文件夹中，如下所示：

paths:
  /api/youtube/youtubeWebhook:
    get:
      summary: Handles YouTube PubSubHubbub webhook verification requests
      description:
        This function....
      parameters:
...
  /api/youtube/...:
etc...

我的文件夹树：

./
├── global.yaml
└── youtube.yaml

顺便说一句，我知道这是 $ref 的问题，因为我尝试将路由放入我的 global.yaml 中，并且它显然正在工作并显示在我的文档中，因此它与我提供的文件夹/路径有关$参考。 我从 Swagger 得到的错误是：错误：$ref 处的解析器错误 无法解析引用：针对意外元素评估令牌“路径”时，JSON 指针评估失败

任何人都可以告诉我如何处理这个问题吗？ 我可以尝试其他解决方案来代替这个吗？

提前致谢！

尝试将路由放入 global.yaml 的路径中，成功了。

这显然是 #paths 的解析错误，我不知道如何修复，因为 github 上唯一类似的问题不幸被关闭而没有答案。

我希望youtube路线能够被正确解析，避免以后再犯错误

Answer 1

我回来了

为有需要的人提供解决方案：

$ref 确实不错，但是我发现要让 $ref 生效，需要将 yaml 捆绑在一起。只有这样，它才会搜索 $ref 路径并执行相应操作。

您可以使用 swagger-cli 或 redocly :)（swagger-cli 已弃用）

祝你好运