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