I am using NSwag in a .NET environment to generate a C# client from an OpenAPI 3.0.1 specification. My OpenAPI specification includes components that are defined in external files, but NSwag is failing to resolve these external references, specifically with nested schemas.

When attempting to generate the C# client, I encounter errors like System.InvalidOperationException: Could not resolve the path ‘#/components/schemas/SomeSchema’. This error suggests that NSwag cannot resolve the external references, even though the paths are correctly specified.

Here is what the ref looks like:

components:
  schemas:
    SomeSchema:
      $ref: './external_definitions.yml#/components/schemas/SomeSchema'

I’ve confirmed the file paths are correct relative to where NSwag is executed.
Tried simplifying the $ref to reference simpler schemas which worked, but nested ones fail.

The reason I am doing this is because, I want to have a spec for a gateway use schemas for a spec from another service, and to avoid duplicating these.

Another option which seemed to work was having the nested schemas also be referenced, but, there are too many and ultimately this becomes very messy to me.

Has anyone successfully resolved external $ref paths with nested schemas using NSwag?

Are there any specific configurations or workarounds in NSwag or NJsonSchema that I might be missing to handle this situation better?

Any help or pointers towards what might be going wrong or how to fix it would be greatly appreciated.