Swagger

Question

我有一个 API returns 以下成功响应：

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

或失败时类似下面的内容：

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

文件名属性仅在请求成功时指定，但如果出现错误，则会提供一条消息。这意味着消息和文件名属性是 "optional" 但结果属性是必需的。

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

"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"，并且对所有错误响应只能使用单一结构，或者是否有一种方法可以指定某些属性在定义中是可选的？

Answer 1

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

正确的形式是：

    "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 属性中的都被认为是可选的。请记住，这意味着可以同时获得 message 和 filename.

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

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

如果您仍然可以修改 API，我强烈建议使用状态代码进行区分，甚至使用微调的区分，例如 200 表示 GET 操作成功，201 表示成功 POST（或创建）操作等，基于此处的定义 - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

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

Swagger - Specify Optional Object Property or Multiple Responses

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