How using ref into examples Swagger?

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.