在 Open API Doc 中包含多个文件路径

Question

我有一个相当大的 API，其中有很多轮子在转动。将所有这些记录在一个巨大的 openapi.yaml 文件中对我来说并不容易，因此我决定将文档分解为单独的 paths，如下面的屏幕截图所示：

现在在我的customer.yaml 文件中，我有以下路线：

/customers/new:
/customers/login:
/customers/logout:

在我的partner.yaml 文件中，我有以下路线：

/partners/new:
/partners/login:
/partners/logout:

现在我将以上两个文件包含在我的最终index.yaml 文件中，如下所示

paths:
  - $ref: "./paths/partner.yaml"
  - $ref: "./paths/customer.yaml"

但swagger-cli 最终生成的文档是在路径引用之前添加- 字符，从而导致格式错误的不可用文档。

我该如何解决这个问题？

Answer 1

OpenAPI 中的paths 是映射，而不是数组，所以不能使用 yaml - 语法。

您需要在顶级文件中包含 pathItem 键，并将 $refs 放入相关文件或文件片段中。

例如：

paths:
  /foo:
    $ref: "./foo.yaml"
  /bar:
    $ref: "./paths.yaml#/paths/bar"