Как использовать ref в примерах Swagger?

Question

Как использовать ref в примерах Swagger?

JSON spec:

"responses": {
"200": {
"description": "Успешный ответ сервиса",
"schema": {
"$ref": "#/definitions/BaseResponse"},
"examples": {
"application/json": {
"status": true,
"response": {
"$ref": "#/definitions/Product"},
"errors": null
}
}
}
}

Результат:

Но мне нужно:

{
"status": true,
"response": {
"ProductNumber": "number",
"Barcode": "number",
"Length": 12,
"Width": 34,
"Height": 423,
"Volume": 1232
}
},
"errors": null
}

Как я могу использовать $ refs в массиве примеров для ответа в произвольном формате?
Это типичный случай, но я не могу найти документацию для него. Спасибо за ваш отзыв.

2

php swagger swagger-2.0 swagger-ui

Решение

Другие решения

Других решений пока нет …

Источник

Accepted Answer

Встроенные примеры не поддерживают $ref — пример должен быть полным примером:

      "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
}
}
}
}

Вместо того, чтобы использовать responses.<code>.examples, вы можете указать значения примера в вашем BaseResponse схема, и Swagger UI будет использовать их вместо этого.

Например, вы можете добавить полный пример к вашему BaseResponse схема:

  "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
}
}
}

или используйте примеры на уровне свойств:

  "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             // <------
},
...
}
}
}

Я хотел бы отметить, что "errors": null а также "example": null на самом деле не действительны в OpenAPI 2.0 (fka Swagger), потому что он не поддерживает обнуляемые типы. Обнуляемые типы поддержанный только в OpenAPI 3.0.

1