Forum Discussion

nickdunkin's avatar
nickdunkin
New Contributor
4 years ago

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...
  • mhiggins's avatar
    mhiggins
    4 years ago

    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. 

mhiggins's avatar
mhiggins
Staff

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. 

 

nickdunkin's avatar
nickdunkin
New Contributor
4 years ago

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's avatar
    mhiggins
    Staff
    4 years ago

    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. 

    • nickdunkin's avatar
      nickdunkin
      New Contributor
      4 years ago

      Got it.  Thanks.

       

      Appreciate the help.

       

      Nick