Ask a Question

Swagger $ref won't work

New Contributor

Swagger $ref won't work


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 - 

Capture.PNGAnd 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 😊

SmartBear Alumni (Retired)

Hi lizat2110,


Please check if the following article helps you resolve the current issue:

Tanya Yatskovskaya
SmartBear Community and Education Manager

Hey, I came across this article earlier and unfortunately, it wasn't helpful for my problem.

SmartBear Alumni (Retired)


What can we recommend here?

Tanya Yatskovskaya
SmartBear Community and Education Manager

Not sure of the use case. Is version Swagger 2.0? or OAS 3.0?
Any ways, not tried swagger-ui-express ever.

Using swagger-editor and can use "$ref" in the swagger definition 2.0 and generate java code which is perfectly fine.

Community Hero

By the way, is it possible to show the swagger definition for review?

SmartBear Alumni (Retired)

Hi lizat2110,


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:

Helen Kosova
SmartBear Documentation Team Lead
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
Showing results for 
Search instead for 
Did you mean: