cancel
Showing results for 
Search instead for 
Did you mean: 

$ref in response example relative to response example

SOLVED
Highlighted
New Contributor

$ref in response example relative to response example

I am using a $ref in a Swagger 2.0 API response example that, when the response is returned, is interpreted correctly as relative to the response itself:

responses:
  200:
    description: OK
    schema:
      "$ref": "#/definitions/CollectionOfFoos"
    examples:
      application/json:
        foos:
          - id: 00000000-0000-0000-0000-000000000000
            name: sample foo 0
            bar:
              id: 0
              "$ref": "#/refs/bars/0"
            baz:
              id: 42
              "$ref": "#/refs/bazzes/myBaz"
          - id: 00000000-0000-0000-0000-000000000001
            name: sample foo 1
            bar:
              "$ref": "#/refs/bars/0"
            baz:
              "$ref": "#/refs/bazzes/myOtherBaz"
        refs:
          bars:
            0:
              detail: "Additional detail about this bar..."
          bazzes:
            myBaz:
              detail: "Additional detail about this baz..."
            myOtherBaz:
              detail: "Additional detail about this other baz..."

So, were that example response to be sent to a consumer, the pointer in those $refs would point to the refs member on the response. This is a contrived example, but we do this for "normalization" purposes, so that more than one foo can refer to the same bar or baz.

The problem is that this doesn't comply with the spec, since those $ref elements that will later resolve correctly don't do so when the API including examples is checked for compliance. That first $ref("$ref": "#/definitions/CollectionOfFoos") is perfectly compliant, since in the API doc there is something at definitions/CollectionOfFoos, but there isn't anything at refs/bazzes/myBaz, etc., so those lines throw an error with the description $refs must reference a valid location in the document. Is there any way around this, or a better way to approach this problem?

1 ACCEPTED SOLUTION

Accepted Solutions
Moderator

Re: $ref in response example relative to response example

Hi Brennon,

 

Your definition is perfectly valid.

 

Swagger UI and Swagger Editor are not supposed to resolve those $ref: "#/refs/..."  that are part of example values. The issue is tracked here:

https://github.com/swagger-api/swagger-ui/issues/4765

https://github.com/swagger-api/swagger-editor/issues/2031


Helen Kosova
SmartBear Technical Writer
________________________
Vote up helpful replies.
Accept this reply if you think it's the best solution to your question.
2 REPLIES 2
Moderator

Re: $ref in response example relative to response example

Hi Brennon,

 

Your definition is perfectly valid.

 

Swagger UI and Swagger Editor are not supposed to resolve those $ref: "#/refs/..."  that are part of example values. The issue is tracked here:

https://github.com/swagger-api/swagger-ui/issues/4765

https://github.com/swagger-api/swagger-editor/issues/2031


Helen Kosova
SmartBear Technical Writer
________________________
Vote up helpful replies.
Accept this reply if you think it's the best solution to your question.
New Contributor

Re: $ref in response example relative to response example

Thats great to know. Thanks for the response!

New Here?
Join us and watch the welcome video:
Watch the New Interview
APITestingMistake#2
Top Kudoed Authors