Possible bug in JSON generation when using reusable examples from components/examples
Per documentation at https://swagger.io/docs/specification/adding-examples/ I should be able to define examples of schema objects and use them in request/response bodies. When defining a request body content like so:
...
content:
application/json:
schema:
$ref: "#/components/schemas/BidLineSummary"
examples:
objectExample:
$ref: "#/components/examples/BidLineSummaryCapExample"
...
The generated API shows no values from the referenced example, but does show the object model and it's field defaults.
Changing up the above to be:
...
content:
application/json:
schema:
$ref: "#/components/schemas/BidLineSummary"
example:
BidLineSummaryCapExample:
$ref: "#/components/examples/BidLineSummaryCapExample"
...
(note example with 's' removed)
gives generated JSON like:
{
"BidLineSummaryCapExample": {
"value": {
"id": "bb89c07f-0f1b-47a9-bcac-ff9ac4f44ee0",
"bidMonth": 11,
"bidYear": 2018,
"baseName": "mem11",
"seatPosition": "CAP",
"userEnteredPilotCount": 365,
"systemPilotCount": null,
"userEnteredPayOnlyPilotCount": 52,
"systemPayOnlyPilotCount": null,
"userEnteredRegularLineCount": 208,
"systemRegularLineCount": null,
"suggestedRegularLineCount": null,
"userEnteredReserveLineCount": 34,
"systemReserveLineCount": null,
"suggestedReserveLineCount": null,
"userEnteredSecondaryLineCount": 71,
"systemSecondaryLineCount": null,
"suggestedSecondaryLineCount": null
},
"$$ref": "#/components/examples/BidLineSummaryCapExample"
}
}
Why is it returning the $ref definition after the object body? The JSON is entirely wrong as the correct output should be:
{
"id": "bb89c07f-0f1b-47a9-bcac-ff9ac4f44ee0",
"bidMonth": 11,
"bidYear": 2018,
"baseName": "mem11",
"seatPosition": "CAP",
"userEnteredPilotCount": 365,
"systemPilotCount": null,
"userEnteredPayOnlyPilotCount": 52,
"systemPayOnlyPilotCount": null,
"userEnteredRegularLineCount": 208,
"systemRegularLineCount": null,
"suggestedRegularLineCount": null,
"userEnteredReserveLineCount": 34,
"systemReserveLineCount": null,
"suggestedReserveLineCount": null,
"userEnteredSecondaryLineCount": 71,
"systemSecondaryLineCount": null,
"suggestedSecondaryLineCount": null
}
Which is the same output generated when defining the exact same example directly within the request body like so:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BidLineSummary'
example:
id: bb89c07f-0f1b-47a9-bcac-ff9ac4f44ee0
bidMonth: 11
bidYear: 2018
baseName: mem11
seatPosition: CAP
userEnteredPilotCount: 365
systemPilotCount: null
userEnteredPayOnlyPilotCount: 52
systemPayOnlyPilotCount: null
userEnteredRegularLineCount: 208
systemRegularLineCount: null
suggestedRegularLineCount: null
userEnteredReserveLineCount: 34
systemReserveLineCount: null
suggestedReserveLineCount: null
userEnteredSecondaryLineCount: 71
systemSecondaryLineCount: null
suggestedSecondaryLineCount: null
It appears this is a bug with the JSON generation when using $ref to components/examples. Any help would be appreciated as we can workaround currently by defining all examples in the request/response bodies but it would be much more useful to be able to have reusable examples.
Thanks,
Nate Brandeburg
UPDATE:
Response from Support (Thanks Wesley!):
I received an update from the dev team regarding this issue.
It seems to be working as expected, somewhat.
There's a difference between 'example' and 'examples'. 'example' can contain a single example value and cannot reference an external example. The value of 'example' will be taken as-is, and that's the result in the current API definition.
'examples' can contain multiple named examples, and these examples can have references.
To solve the issue, you would either change the 'example' to 'examples' and leave the rest as-is, or remove the name of the example under the 'example' and inline the value instead of referencing.
The issue as of now however is that we currently support rendering of 'example' but not plural 'examples'. So, you will notice that using examples does not return correctly either.
Adding the use of 'examples' is currently being track by our team. Currently I would advise you to keep defining the examples directly.
Once again I apologize for any inconvenience.Seems that defining them per request/response body is the only way to produce valid JSON for client consumption until examples support is implemented.
