cancel
Showing results for 
Search instead for 
Did you mean: 

Swagger $ref won't work

Highlighted
New Contributor

Swagger $ref won't work

Hey, 

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 😊

6 REPLIES 6
Community Manager

Re: Swagger $ref won't work

Hi lizat2110,

 

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

https://swagger.io/docs/specification/using-ref/

---------
Tanya Gorbunova
SmartBear Community Manager

Join the September Hub-bub to show off, learn and win
New Contributor

Re: Swagger $ref won't work

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

Community Manager

Re: Swagger $ref won't work

Community, 

What can we recommend here?

---------
Tanya Gorbunova
SmartBear Community Manager

Join the September Hub-bub to show off, learn and win
Community Hero

Re: Swagger $ref won't work

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.


Regards,
Rao.
Community Hero

Re: Swagger $ref won't work

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


Regards,
Rao.
Moderator

Re: Swagger $ref won't work

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: https://azimi.me/2015/07/16/split-swagger-into-smaller-files.html#tools


Helen Kosova
SmartBear Technical Writer
________________________
Vote up helpful replies.
Accept this reply if you think it's the best solution to your question.

Join the September Hub-bub to show off, learn and win
New Here?
Join us and watch the welcome video:
SeptemberNews
Join our online event
SeptemberHubBub
Top Kudoed Authors
Join the September Hub-bub to show off, learn and win