无法创建通用API响应的大胆定义

Question

我的服务器应用程序以以下格式发送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内容对于每个响应都是清楚的。