swagger-3.0 - 无法创建通用 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都很清楚。