路径中具有多个/连续 $ref 元素的 OpenApi 文件给出了重复的映射键

Question

我有以下 OpenAPI 文件，我的目的是在其自己的 yaml 文件中定义员工、客户、项目端点。但是，使用下面的代码会导致“重复映射键”错误——这是因为使用了“$ref”（连续）。有没有办法实现这种隔离？

openapi: 3.0.3
info:
  title: example  
servers:
  - url: https://example.net/api
security:
  - apiKey: []
paths:
  $ref: './employee/resource.api.yaml'
  $ref: './projects/resource.api.yaml'
  $ref: './customers/resource.api.yaml'

已更新文件内容： 员工/resource.api.yaml

/employee/{id}
  get:
  ...
/employee/{id}/addresses
  get:
  ...

项目/resource.api.yaml

/projects/{id}
  get:
  ...
  put:
  ...
/projects/{id}/files
  get:
  ...
/projects/{id}/fies/{fileName}/Content
  get:
  ...

Answer 1

paths 节点本身不支持$ref。您只能引用单个路径的内容：

paths:
  /employee/{id}:
    $ref: './employee/employeeById.yaml'

  /projects/{id}:
    $ref: './project/projectById.yaml'

员工/employeeById.yaml：

get:
  operationId: ...
  summary: ...
  ...

project/projectById.yaml:

get:
  operationId: ...
  summary: ...
  ...

put:
  operationId: ...
  summary: ...
  ...

---

或者，如果您想保持当前的 resource.api.yaml 文件不变，$refs 将如下所示。有关 #/... 指针如何在 $ref 值中编码的说明，请参阅 this answer。

paths:
  /employee/{id}:
    $ref: './employee/resource.api.yaml#/employee~1%7Bid%7D'

  /employee/{id}/addresses:
    $ref: './employee/resource.api.yaml#/employee~1%7Bid%7D~1addresses'

  /projects/{id}:
    $ref: './project/resource.api.yaml#/projects~1%7Bid%7D'