cancel
Showing results for 
Search instead for 
Did you mean: 

Understanding $ref - new user to Swagger Hub

SOLVED
nickdunkin
New Contributor

Understanding $ref - new user to Swagger Hub

Hi,

 

New to Swagger so be gentle 🙂

 

I've imported two yaml API docs into SwaggerHub.  They are both OpenAPI v3.0.1

 

The documents contain local $ref entries which seem to work correctly (.i.e. I can "Jump To" them in the UI)

 

One document also contain $ref entries that refer to the other document.  These I simply cannot get to resolve in the UI.

 

$ref: './sva_oc_cdni_openapi.yaml#/components/schemas/FCI_genericbase'

 

Please can someone tell me what I'm doing wrong?

 

Many thanks

 

Nick

 

 

 

 

1 ACCEPTED SOLUTION

Accepted Solutions
mhiggins
Staff

Re: Understanding $ref - new user to Swagger Hub

Domains are just APIs without paths. So if you export a domain to a flat file it can still be consumed in the $ref, but not as a URL as it is in SwaggerHub. e.g. the way you do now. 

Also, if you export your API that has domain references in Resolved format (json or yaml) all remote references will be resolved into local anchors. 

View solution in original post

4 REPLIES 4
mhiggins
Staff

Re: Understanding $ref - new user to Swagger Hub

Hi Nick,

 

In SwaggerHub we are expecting remote $ref to refer to content inside a Domain, not an API flat file. 

Create a new Domain and add your remote components to it. Then replace the faulty $ref in your original APIs with the new domain anchor. 

type: $ref: and then press control-space, SwaggerHub will show you all the domain anchors that are available and you click the one you want. 

The auto-complete is context sensitive. If you are in a place needing parameters, you will only see parameter anchors, if you need a schema control-space will show you all the schemas in your domains. Yes you can have more then 1 domain. 

 

Tags (3)
nickdunkin
New Contributor

Re: Understanding $ref - new user to Swagger Hub

Thank you for the clarification.  One follow up.

 

"In SwaggerHub we are expecting remote $ref to refer to content inside a Domain, not an API flat file."

 

Please can you clarify, is that a SwaggerHub constraint, or an OpenAPI 3 constraint?

 

I am working with partners who may or may not be using SwaggerHub, but they are using OpenAPI 3.  Do I have an interoperability issue?

 

Thanks

 

mhiggins
Staff

Re: Understanding $ref - new user to Swagger Hub

Domains are just APIs without paths. So if you export a domain to a flat file it can still be consumed in the $ref, but not as a URL as it is in SwaggerHub. e.g. the way you do now. 

Also, if you export your API that has domain references in Resolved format (json or yaml) all remote references will be resolved into local anchors. 

View solution in original post

nickdunkin
New Contributor

Re: Understanding $ref - new user to Swagger Hub

Got it.  Thanks.

 

Appreciate the help.

 

Nick

New Here?
Join us and watch the welcome video:
Announcements