$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 $ref
s 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?
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: