OpenAPI file, reference to a component from another file does not work

Question

I want to split my OpenAPI file components to separate files and reuse them in my documentation. My problem is that although my IDE finds the reference of my component in another file the Swagger parser throws an error. My files are in the same folder and based on the documentation we can access external component. I am using OpenAPI 3.0.0.

The error I am getting is this:

Unable to resolve resource /C:/wamp/www/justbe/documentation/API_Specs/Components/Application.yaml/General.yaml/

Seems like the parser tries to find the other yaml file under the one I am calling the reference:

Note: although the error the Swagger plugin in my PhpStorm displays the structure in the editor however, I cannot merge all files to one because of the issue. I tried also VS Code, same issue.

Answer 1

Update your reference uri to the following:

$ref: './General.yaml#/components/schemas/Note'

Note the # must be in the same path segment as the file path because it acts as the "anchor" to that file. The reference parser then uses the base path uri to traverse the document tree.

Answer 2

So I managed to find a solution and I will post it here for anyone will face a similar problem.

So, my main issue is that I didn't follow 100% the guidelines. I read this article and I noticed 1 main problem with my approach.

Firstly, I didn't split my schemas in separate files. By mixing up many entities in one file it becomes very complicated to set it up and maintain. Therefore, what the article suggests and I agree is split all of your entities in different files. For example here is my schema for note entity. You should do that for all your entities:

Then you can reuse this schema anywhere like the image below. In that case the application file is in the same level as note. But note schema can be used also in other folders as it is descripted in the documentation.

Last but not least, OpenAPI file parser does not return always accurate errors therefore you need to keep your file structure as simple as possible to be able to maintain it. I am using OpenAPI ​(Swagger)​ Editor v1.82 plugin in IntelliJ IDE