How using ref into examples Swagger? - php

Question

JSON spec:
"responses": {
"200": {
"description": "Успешный ответ сервиса",
"schema": {
"$ref": "#/definitions/BaseResponse"
},
"examples": {
"application/json": {
"status": true,
"response": {
"$ref": "#/definitions/Product"
},
"errors": null
}
}
}
}
Result:
But I need:
{
"status": true,
"response": {
"ProductNumber": "number",
"Barcode": "number",
"Length": 12,
"Width": 34,
"Height": 423,
"Volume": 1232
}
},
"errors": null
}
How I can using $refs into example array for custom format response?
It's a typical case, but I cannot found documentation for it. Thank you for you feedback.

Answer 1

Inline examples do not support $ref - the example must be a complete example:
"responses": {
"200": {
"description": "Успешный ответ сервиса",
"schema": {
"$ref": "#/definitions/BaseResponse"
},
"examples": {
"application/json": {
"status": true,
"response": {
"ProductNumber": "number",
"Barcode": "number",
"Length": 12,
"Width": 34,
"Height": 423,
"Volume": 1232
},
"errors": null
}
}
}
}
Instead of using responses.<code>.examples, you can specify the example values in your BaseResponse schema, and Swagger UI will use those instead.
For example, you can add a complete example to your BaseResponse schema:
"definitions": {
"BaseResponse": {
"type": "object",
"properties": {
"status": {
"type": "boolean"
},
...
},
"example": { // <------ schema-level example
"status": true,
"response": {
"ProductNumber": "number",
"Barcode": "number",
"Length": 12,
"Width": 34,
"Height": 423,
"Volume": 1232
},
"errors": null
}
}
}
or use property-level examples:
"definitions": {
"BaseResponse": {
"type": "object",
"properties": {
"status": {
"type": "boolean",
"example": true // <------
},
"response": {
"$ref": "#/definitions/Product"
},
"errors": {
"example": null // <------
}
}
},
"Product": {
"type": "object",
"properties": {
"ProductNumber": {
"type": "string",
"example": "number" // <------
},
"Length": {
"type": "integer",
"example": 12 // <------
},
...
}
}
}
I'd like to note that "errors": null and "example": null are not actually valid in OpenAPI 2.0 (fka Swagger), because it does not support nullable types. Nullable types are supported in OpenAPI 3.0 only.

Answer 2

I'v tried many solutions, the only one that seems to work is using 'examples' key and not 'example'.
then put a single example (you should name it) and put the $ref under it.
just like this:
"responses": {
"200": {
"description": "Успешный ответ сервиса",
"schema":
"$ref": "#/definitions/BaseResponse"
"examples":
"example_name": # You can give as an example name any name you want
$ref: "#/examples/200_res"
examples:
200_res:
description: example for 200_res
value:
{
"status": true,
"response": {
"ProductNumber": "number",
"Barcode": "number",
"Length": 12,
"Width": 34,
"Height": 423,
"Volume": 1232
},
"errors": null
}
also notice you have problems with your { } at the example you added