swaggerhub and path references don't work

[Jeffrey Haynes]

I am trying to split up a huge yaml into smaller pieces. I'm trying to use the $ref as specified in the Path Item Object in the spec. But swaggerhub and swagger-editor have issues with this. Do I have the syntax correct? What am I missing?

swagger: '2.0'

info:

  version: '2.0'

consumes:

  - application/json

produces:

  - application/json

paths:

  /cars:

    $ref: 'paths/cars.yaml'

    # get:

    #   description: Test

    #   responses:

    #     200:

    #       description: Success

[Ron Ratovsky]

Hi Jeffery!

We just announced last week a new feature in SwaggerHub – Domains. Domains are pretty much a way to split your specs into smaller files.

Each domain can contain path items, responses, parameters and definitions to which you can reference from other domains and APIs.

There’s also an autosuggest feature that will help you put in the right URL to those definitions (details in the linked announcement).

If you have any further questions about SwaggerHub, please user our Community Forums.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Jeff Haynes]

Thanks Ron.

I have looked into the Domains on swaggerhub.

1. I created a domain with a simple object, but don't seem to be able to reference it from my API definition.
2. Does this concept translate to swagger specs not hosted on swaggerhub? If not, then it is not something I can use a lot at this point.

Thanks for you help!

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Jeff Haynes]

Also,

My question is less about swaggerhub and more about relative references in swagger. If the tools do not recognize them, then how do I ensure that the relative references work correctly?

Thank you,

Jeff

[tony tam]

Hi Jeff,

A couple things.  First, swaggerhub facilitates a standard usage of references.  So you don't need to use swaggerhub to use references, it just makes it easy to, and by a concept of Domains.

Next, references are widely supported across most all of the popular tools.  Things start getting more complicated (for all involved) when they are relative.  For example, try putting this into your definition:

paths:

  /test:

    $ref: 'https://api.swaggerhub.com/domains/fehguy/common/1.0.0#/pathitems/EntityOperations'

Note that reference lives in swaggerhub but swagger editor and even your own api definition will find it just fine.  As you probably notice though, this is an absolute reference.

For other tooling, such as swagger-ui, swagger parser, etc., relative references behave fine, but note the term `relative` means they need to be `relative to something`.  The swagger-editor--which allows you to edit a definition without the notion of being "hosted", makes this impossible.

So I do suggest looking at your domain on swaggerhub, if it is a valid entry in the `pathitems` section (see the sample domain that I reference above: https://swaggerhub.com/domains/fehguy/common/1.0.0

It will resolve fine.

If you are trying to resolve a domain inside your api definition, it will auto-complete if it under the same "ownership".  That is, if it's under your account or organization (fehguy in my case), you can press "option + space" on a mac or "ctrl + space" directly after typing "$ref:".

Let me know if that answers your question