Невозможно создать простое определение общего ответа API
Мой сервер приложение отправляет json
ответ в следующем формате
{
result: ... //this could be success or error
additional-info: ... //this is a wrapper and could contains information depending the the operation
}
additional-info
может быть сообщением об успешном выполнении (например, "операция выполнена успешно"), сообщением об ошибке (например, "операция не выполнена") или, скажем, объект в строковом формате (например, {user-name: manu}
,
Я создал swagger
определение вышеуказанного объекта следующим образом:
ServerSuccessResponse:
type: object
properties:
result:
type: string
enum:
- success
additional-info:
type: string
enum:
- SuccessMessages
- UserResponse
required:
- result
- additional-info
ServerFailureResponse:
type: object
properties:
result:
type: string
enum:
- error
additional-info:
type: string
enum:
- FailureMessages
Затем я пытаюсь использовать приведенное выше определение в API следующим образом
/user/username:
post:
tags:
- new user
summary: Add a new user to the database
description: Use this path to add a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'200':
description: means the user was added successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ServerSuccessResponse'#BUT ITS NOT CLEAR WHAT ADDITIONAL-INFO CONTAINS
'404':
description: >-
Only a signed in user can add a question. This response means that
the user isn't signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerFailureResponse' #BUT ITS NOT CLEAR WHAT ADDITIONAL-INFO CONTAINS
'500':
description: >-
means some internal error occur on the server while doing the
operation. The state of the operation if un-determined and the
operation could be successful, failed or partially successful
(because some database operations are not rolled back if error
occurs!
content:
application/json:
schema:
$ref: '#/components/schemas/ServerFailureResponse'#BUT ITS NOT CLEAR WHAT ADDITIONAL-INFO CONTAINS
Моя проблема в том, что на данный момент, ServerFailureResponse
или же ServerSuccessResponse
не говорит что additional-info
будет содержать. Я хотел бы изменить определение API так, чтобы то, что содержится в additional-info
также становится ясно. Есть ли способ, которым я мог бы сделать это? В коде я все еще хочу использовать additional-info
как обертка. Я хочу только этого в Swagger
содержание additional-info
ясно для каждого ответа.