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" и отображает следующее сообщение об ошибке:

enter image description here

Когда я смотрю пример с swagger, у них есть следующий макет, в котором вместо одного есть два разных определения ответа.

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

Я мог бы это сделать, но, похоже, не может быть нескольких ответов для кода ошибки 200. Означает ли это, что нужно использовать "по умолчанию" для всех ответов об ошибках, и для всех ошибочных ответов может быть только одна структура, или есть способ указать, что определенные атрибуты являются необязательными в определениях?

Ответы

Ответ 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.