I started to use swagger with swagger-ui-express and swagger-jsdoc to auto document my existing api, which is written with nodejs and express (like described here - example).I came across a problem when I tried to add a $ref to an existing json schema file (that sits inside my project on the same directory as all my js files) on my annotation.
My directory looks like this -
And my annotation looks like this -
/** * @swagger * /testing: * get: * description: This should show the json schema * responses: * 200: * description: "successful operation" * schema: * $ref: "schema.json" */
I wrote the local path(as writen above) and the absolute path, tried to use #, using many syntaxes and nothing worked, i keep geting the same error -
Resolver error at paths./testing.get.responses.200.schema.$ref Could not resolve reference: Tried to resolve a relative URL, without having a basePath. path: 'schema.json' basePath: 'undefined'
I looked the problem up online and couldn’t find any clear answer. I saw a solution that suggested I should put my schema on a server and access it with an url address and I prefer not to do it on this point.
Also, at some point I put the scheme into a variable and then put it in the $ref and it worked. The only problem was that the scheme included some inner refs to element in the same file and swagger didn’t even resolved those.
Is there a way to work with $ref in swagger-ui-express?
Thank you 😊
I'm not familiar with swagger-ui-express as it's not one of our projects, but it appears that it does not support $refs:
>> this module will only deal with one full swagger document
You'll probably need to use a preprocessor such as json-refs to resolve the $refs and then pass the full resolved spec to swagger-ui-express. You can find an example of using json-refs in the "Tools" section here: https://azimi.me/2015/07/16/split-swagger-into-smaller-files.html#tools