Swagger - 指定可选对象属性或多个响应 [英] Swagger - Specify Optional Object Property or Multiple Responses

问题描述

我有一个 API 可以在成功时返回以下响应:

I have an API that either returns the following response on success:

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

或失败时类似以下内容:

or something like below upon failure:

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

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

The filename property is only specified if the request was a success, but a message is provided if there was an error. This means the message and the filename properties are "optional" but the result property is required.

我尝试在定义中定义这个响应对象，如下所示:

I tried defining this response object in a definition as shown below:

"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"属性，会显示如下错误信息:

But it appears that swagger does not like the "required" attribute and will show the following error message:

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

When I look at an example from swagger, they have the following layout where there are two different response definitions instead of one.

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

我可以这样做，但似乎不能对 200 错误代码有多个响应.这是否意味着必须对所有错误响应使用默认"，并且对于所有错误响应只能有一个结构，或者有没有办法指定某些属性在定义中是可选的?

I could do this, but it appears that one cannot have multiple responses for the 200 error code. Does this mean that one has to use "default" for all error responses, and one can only have a single structure for all erroneous responses, or is there a way to specify that certain attributes are optional in definitions?

推荐答案

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

You're getting the error in the model, because that's not the way to define required properties.

正确的形式是:

    "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 属性中的内容都被认为是可选的.请记住，这意味着有可能获得 both message 和 filename.

Anything not in the required property is assumed to be optional. Keep in mind that this implies that it's possible to get both message and filename.

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

You can then use this model for your 200 response.

但是，当涉及到 REST API 设计时，这违反了更常见的标准之一.取自 HTTP 协议的状态代码旨在传达操作的结果.2XX 用于成功响应，4XX 用于错误的用户输入，5XX 用于服务器端的问题(3XX 用于重定向).您在这里所做的是告诉客户端-操作成功，但实际上可能是错误.

However - when it comes to REST API design, this breaks one of the more common standards. The status codes, taken from the HTTP protocol are meant to convey the outcome of the operation. 2XX are used for successful responses, 4XX are for errors due to bad user input, 5XX are for problems on the server side (3XX are for redirects). What you're doing here, is tell the client - the operation was successful, but in fact, it can be an error.

如果您仍然可以修改 API，我强烈建议您使用状态码进行区分，即使使用微调的区别，例如 200 表示成功的 GET 操作，201 表示成功的 POST(或创建)操作等等关于，根据这里的定义 - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

If you can still modify the API, I'd highly recommend making that distinction using the status codes, even using the fine tuned distinctions such as 200 for a successful GET operation, 201 for successful POST (or creation) operation and so on, based on the definitions here - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

这篇关于Swagger - 指定可选对象属性或多个响应的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！