My server application sends json
response in the following format
{
result: ... //this could be success or error
additional-info: ... //this is a wrapper and could contains information depending the the operation
}
additional-info
could be a success message (eg "operation successful"), error message (eg "operation failed") or say an object in string format (eg {user-name: manu}
.
I have created swagger
definition of the above object as follows:
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
Then I am trying to use the above definition in APIs as follows
/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
My issue is that at the moment, ServerFailureResponse
or ServerSuccessResponse
doesn't tell what additional-info
would contain. I would like to redesign the API definition such that what is contained in the additional-info
also gets clear. Is there a way I could do it? In code, I still want to use additional-info
as wrapper. I only want that in Swagger
, the content of additional-info
is clear for each response.