Невозможно создать простое определение общего ответа 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 ясно для каждого ответа.

0 ответов

Другие вопросы по тегам