0

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.

Manu Chadha
  • 15,555
  • 19
  • 91
  • 184
  • Can you add some examples of real responses with various `additional-info` values, including the one with "an object in string format (eg `{user-name: manu}`"? – Helen Nov 27 '18 at 20:12
  • eg for 200 response - `{result:"success", additional-info:"{username:manu}"`, for 500 response `{result:error, additional-info:"Operation unsuccessful"}` or 404 response `{result:"success", additional-info:"Not found"}` – Manu Chadha Nov 27 '18 at 20:53

0 Answers0