Support $ref references to separate files in OpenAPI specifications.

[naaeef]

Is your feature request related to a problem? Please describe.
I'd like to generate the refit internfaces for an OpenAPI specification that consists of multiple files that are linked to each other using $ref (see https://swagger.io/docs/specification/using-ref/).

Describe the solution you'd like
It would be great if refitter would support $ref.

Describe alternatives you've considered
The alternative would be to merge the files first using a different tool. But it would be much easier, if this extra step could be avoided.

Additional context
Thank you for your help.

[christianhelle]

@naaeef thanks for taking the time to report this

I was unaware of this feature in the OpenAPI spec. Do you have an example spec that does this? I use NSwag to parse the OpenAPI spec, it might even already be supported out of the box, but I don't know

[kami-poi]

@christianhelle Hello,
I have the same suggestion. Here I have an example using separate files. Please see this repo. All the schemas are defined in components.yaml while request pathes in openapi.yaml. I hope this may helpful, thanks.

[christianhelle]

@christianhelle Hello, I have the same suggestion. Here I have an example using separate files. Please see this repo. All the schemas are defined in components.yaml while request pathes in openapi.yaml. I hope this may helpful, thanks.

@kami-poi Thanks for the example. This will be a big help!

I'll see what I can do over the holidays

[christianhelle]

@kami-poi I was looking into this today using the repo you provided and it seems like NSwag just doesn't support multiple OAS files. I'll experiment with how far I can get with using the Microsoft OpenAPI toolchain

OpenAPI validation seems to work fine and prints out

OpenAPI statistics:  
 - Path Items: 32    
 - Operations: 46    
 - Parameters: 7     
 - Request Bodies: 21
 - Responses: 46     
 - Links: 0          
 - Callbacks: 0      
 - Schemas: 67

I would hate to have to generate the contracts by hand using the MS OpenAPI toolchain since this is already a solved problem by NSwag

[kami-poi]

@christianhelle It seems that NSwag has some issues with $ref. Refitter can find other OAS files but failed on processing other files' $ref field. So maybe we can load all OAS files and combine them into a single file, and then send it to refitter gengrator. It's similar to preprocessing, and it can make NSwag to correctly handle the following steps.

[christianhelle]

@christianhelle It seems that NSwag has some issues with $ref. Refitter can find other OAS files but failed on processing other files' $ref field. So maybe we can load all OAS files and combine them into a single file, and then send it to refitter gengrator. It's similar to preprocessing, and it can make NSwag to correctly handle the following steps.

@kami-poi This is exactly what I ended up doing!

C:/projects/christianhelle/refitter/src/Refitter/bin/Release/net8.0/refitter.exe C:\projects\github\bot-oas\v1\openapi.remote.yaml
Refitter v1.0.0.0
Support key: ptbddgt

OpenAPI specifications contains external references.                  
Attempting to merge of all external references into single document...
components.yaml - Paths must be a map/object
components.yaml - The field 'paths' in 'document' object is REQUIRED.

OpenAPI statistics:  
 - Path Items: 32    
 - Operations: 46    
 - Parameters: 13    
 - Request Bodies: 21
 - Responses: 46     
 - Links: 0          
 - Callbacks: 0      
 - Schemas: 210

Length: 90275 bytes
Output: C:\projects\christianhelle\refitter\src\Refitter\bin\Release\net8.0\Output.cs
Duration: 00:00:02.5172435

Currently, it supports having external references to files within the same folder, or remotely. But it won't work if the remote file has local external references.

These scenarios work:

• The OAS file /home/christian/openapi.yaml has external references to components.yaml then I expect components.yaml to be in the same folder as /home/christian/openapi.yaml.
• The OAS file /home/christian/openapi.yaml will also work if it has external references to https://somewhere.over.the.rainbow/components.yaml

This scenario doesn't work:

• The OAS file https://somewhere.over.the.rainbow/openapi.yaml has external references to components.yaml

If you can live with this @kami-poi @naaeef then I will merge in my working solution to the main branch and publish a release

[kami-poi]

@christianhelle This is already sufficient for my usage scenario, thank you!

[christianhelle]

@kami-poi @naaeef I released a preview version as version 0.8.7.41-preview containing the fix for this

You can install it with

dotnet tool install --global Refitter --version 0.8.7.41-preview

I'll bundle a few other fixes before I do a full release