В моем "упрощенном" API все ответы производятся (наследуются) из базового класса "ответ". Класс ответа состоит из заголовка, заполненного метаданными, и тела, содержащего основные данные, запрашиваемые пользователем. Ответ (в JSON) выложен таким образом, что все метаданные находятся на первом "слое", а тело - это один атрибут, называемый "тело" как таковой
response
|--metadata attribute 1 (string/int/object)
|--metadata attribute 2 (string/int/object)
|--body (object)
|--body attribute 1 (string/int/object)
|--body attribute 2 (string/int/object)
Я попытался определить эту связь в swagger со следующим JSON:
{
...
"definitions": {
"response": {
"allOf": [
{
"$ref": "#/definitions/response_header"
},
{
"properties": {
"body": {
"description": "The body of the response (not metadata)",
"schema": {
"$ref": "#/definitions/response_body"
}
}
}
}
]
},
"response_header": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string",
"description": "value of 'success', for a successful response, or 'error' if there is an error",
"enum": [
"error",
"success"
]
},
"message": {
"type": "string",
"description": "A suitable error message if something went wrong."
}
}
},
"response_body": {
"type": "object"
}
}
}
Затем я пытаюсь создать разные ответы, создав различные классы body/header, которые наследуют от body/header, а затем создадут классы дочерних ответов, которые состоят из соответствующих классов заголовка/тела (показаны в исходном коде внизу). Тем не менее, я уверен, что либо это неправильный способ сделать что-то, либо что моя реализация неверна. Я не смог найти пример наследования в спецификации swagger 2.0 (показано ниже), но нашел пример composition.
Я вполне уверен, что этот "дискриминатор" играет большую роль, но не уверен, что мне нужно делать.
Вопрос
Может ли кто-нибудь показать мне, как предполагается реализовать композицию + наследование в swagger 2.0 (JSON), предпочтительно путем "исправления" моего примера кода ниже. Было бы замечательно, если бы я мог указать класс ErrorResponse, который наследует от ответа, где атрибут "result" в заголовке всегда задан как "ошибка".
{
"swagger": "2.0",
"info": {
"title": "Test API",
"description": "Request data from the system.",
"version": "1.0.0"
},
"host": "xxx.xxx.com",
"schemes": [
"https"
],
"basePath": "/",
"produces": [
"application/json"
],
"paths": {
"/request_filename": {
"post": {
"summary": "Request Filename",
"description": "Generates an appropriate filename for a given data request.",
"responses": {
"200": {
"description": "A JSON response with the generated filename",
"schema": {
"$ref": "#/definitions/filename_response"
}
}
}
}
}
},
"definitions": {
"response": {
"allOf": [
{
"$ref": "#/definitions/response_header"
},
{
"properties": {
"body": {
"description": "The body of the response (not metadata)",
"schema": {
"$ref": "#/definitions/response_body"
}
}
}
}
]
},
"response_header": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string",
"description": "value of 'success', for a successful response, or 'error' if there is an error",
"enum": [
"error",
"success"
]
},
"message": {
"type": "string",
"description": "A suitable error message if something went wrong."
}
}
},
"response_body": {
"type": "object"
},
"filename_response": {
"extends": "response",
"allOf": [
{
"$ref": "#definitions/response_header"
},
{
"properties": {
"body": {
"schema": {
"$ref": "#definitions/filename_response_body"
}
}
}
}
]
},
"filename_response_body": {
"extends": "#/definitions/response_body",
"properties": {
"filename": {
"type": "string",
"description": "The automatically generated filename"
}
}
}
}
}
Обновление диаграммы
Чтобы попытаться прояснить, что я хочу, я создал основную диаграмму ниже, которая направлена на то, чтобы показать, что все ответы являются экземплярами объекта ответа, которые были построены (состав), используя любую комбинацию объектов response_header и response_body, Объекты response_header и response_body могут быть расширены и вставлены в любой объект ответа, который выполняется в случае filename_response, который использует дочернее имя filename_response_body базового класса response_body. И ошибки, и успешные ответы используют объект "ответ".