Swagger API documentation : "Could not resolve reference: JSONPointer evaluation failed while evaluating token "paths" against an unexpected Element"

Im working on a project containing an API. I'm currently trying to document the API using Swagger.

I want to use an external path for my routes to avoid having more than 2000 lines in my yaml. However I cannot seem to use an external path for my routes, it says the #paths isn't found.

I have a global.yaml which contains the base API documentation, and also the paths for the different routes.

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: "info@email.com"
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

I also wanted to avoid defining each route one by one, but apparently its not possible to reference the whole route. (/api/youtube) using 1 YAML, so for now, this will do.

My youtube.yaml is in the same folder, and it looks like this :

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

tree for my folders:

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

By the way I know it's a problem with the $ref, because I have tried putting the route inside of my global.yaml and it is clearly working and showing in my documentation so it has to do with my folder/path I give to $ref. The error I get from Swagger is : Errors : Resolver error at $ref Could not resolve reference: JSON Pointer evaluation failed while evaluating token "paths" against an unexpected Element

Can anyone give me a clue about how to handle this problem ? Is there other solution I can try instead of this ?

Thanks in advance!!

Tried putting the route inside the path of global.yaml, it worked.

This is clearly a parsing error for the #paths, I don't know how to fix because the only issue similar on github got closed without answers unfortunately.

I want the youtube route to be parsed correctly and avoid making the mistake in the future

When you want to split large YAML files, you should try as much as possible to always bundle the files together before serving them to Swagger UI.

It should help you keeping your code organized without overwhelming your main API file as well. The $ref was valid indeed https://redocly.com/docs/resources/ref-guide