OpenApi file with multiple/consecutive $ref elements in paths is giving duplicate mapping key

Question

I have following OpenAPI file, my intention is to define employee, customer, projects endpoints in its own yaml files. However, using the below code is resulting in 'duplicating mapping key' error - this is because the use of '$ref'(consecutively). Is there a way to achieve this segregation?

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'

Updated with file content: employee/resource.api.yaml

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

projects/resource.api.yaml

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

Answer 1

The paths node itself does not support $ref. You can only reference the content of individual paths:

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

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

employee/employeeById.yaml:

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

project/projectById.yaml:

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

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

---

Alternatively, if you want to keep your current resource.api.yaml files as is, the $refs would look as follows. See this answer for an explanation of how the #/... pointers are encoded in the $ref values.

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'