unable to create swagger definition of generic API response

195 Views Asked by At

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.

0

There are 0 best solutions below