Swagger-指定可选对象属性或多个响应

我有一个API，成功后返回以下响应：

{
    "result": "success",
    "filename": "my-filename.txt"
}

或类似以下失败的情况：

{
    "result": "error",
    "message": "You must specify the xxx parameter."
}

仅当请求成功时才指定filename属性，但如果出现错误，则会提供消息。这意味着消息和文件名属性是“可选”的，但结果属性是必需的

我尝试在定义中定义此响应对象，如下所示：

"my_response_object": {
    "type": "object",
    "properties": {
        "result": {
            "type": "string",
            "description": "value of 'success' or 'error', indicated whether was successful",
            "required": true
        },
        "message": {
            "type": "string",
            "description": "an error message if there was an issue",
            "required": false
        },
        "filename": {
            "type": "string",
            "description": "the filename to return if the request was successful",
            "required": false
        }
    }
}

但swagger似乎不喜欢“required”属性，并将显示以下错误消息：

当我看一个来自swagger的示例时，它们有以下布局，其中有两个不同的响应定义，而不是一个

"responses": {
    "200": {
        "description": "Profile information for a user",
        "schema": {
            "$ref": "#/definitions/Profile"
        }
    },
    "default": {
        "description": "Unexpected error",
        "schema": {
            "$ref": "#/definitions/Error"
        }
    }
}

---

我可以这样做，但是对于200个错误代码，似乎一个不能有多个响应。这是否意味着必须对所有错误响应使用“default”，并且只能对所有错误响应使用单个结构，或者是否有方法指定某些属性在定义中是可选的？

您在模型中得到错误，因为这不是定义所需属性的方法

正确的形式是：

    "my_response_object": {
        "type": "object",
        "required": [ "result" ],
        "properties": {
            "result": {
                "type": "string",
                "description": "value of 'success' or 'error', indicated whether was successful"
            },
            "message": {
                "type": "string",
                "description": "an error message if there was an issue"
            },
            "filename": {
                "type": "string",
                "description": "the filename to return if the request was successful"
            }
        }
    }

假定

required

属性中没有的任何内容都是可选的。请记住，这意味着可以同时获取

消息

和

文件名

然后，您可以将此模型用于200响应

然而，当涉及RESTAPI设计时，这打破了一个更常见的标准。从HTTP协议获取的状态代码旨在传达操作的结果。2XX用于成功响应，4XX用于错误用户输入导致的错误，5XX用于服务器端的问题（3XX用于重定向）。你在这里做的是告诉客户——操作成功了，但事实上，这可能是一个错误

---

如果您仍然可以修改API，我强烈建议您根据此处的定义，使用状态代码进行区分，甚至使用微调的区分，例如200表示成功的GET操作，201表示成功的POST（或creation）操作等等-。

非常感谢您的帮助。我有一种感觉，糟糕的设计可能是一个因素。我将使用状态代码。如果缺少此线程所示的必需参数，则选择正确的响应代码可能会很困难：但最好使用某些参数，而不是什么都不使用。如果您愿意，您可以加入我们的irc频道，我们可以在那里讨论设计问题-对于任何使用YAML编写的人，这将是

必需的：[name]

就在

属性：

前面，作为一个注释，“200错误代码的多个响应”听起来很可疑。为什么在2XX下返回错误？