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.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

 

 

 

 

  • 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
    4 years ago

    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.