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
Highlighted
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 SmartBear Connect next April in Boston to meet with software development, API and testing experts from around the world! Get your ticket today!
Highlighted
New Contributor

Re: Swagger $ref won't work

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

Highlighted
Community Manager

Re: Swagger $ref won't work

Community, 

What can we recommend here?

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

 Join SmartBear Connect next April in Boston to meet with software development, API and testing experts from around the world! Get your ticket today!
Highlighted
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.
Highlighted
Community Hero

Re: Swagger $ref won't work

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


Regards,
Rao.
Highlighted
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
________________________

 Join SmartBear Connect next April in Boston to meet with software development, API and testing experts from around the world! Get your ticket today!