example - Swagger-Especifique propiedad de objeto opcional o respuestas múltiples

swagger ui

Question

Tengo una API que devuelve la siguiente respuesta en caso de éxito:

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

o algo como abajo en caso de fracaso:

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

La propiedad de nombre de archivo solo se especifica si la solicitud fue exitosa, pero se proporciona un mensaje si hubo un error. Esto significa que el mensaje y las propiedades del nombre de archivo son "opcionales", pero la propiedad resultante es obligatoria.

Intenté definir este objeto de respuesta en una definición como se muestra a continuación:

"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
        }
    }
}

Pero parece que a swagger no le gusta el atributo "requerido" y mostrará el siguiente mensaje de error:

Cuando miro un ejemplo de swagger, tienen el siguiente diseño donde hay dos definiciones de respuesta diferentes en lugar de una.

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

Podría hacer esto, pero parece que uno no puede tener múltiples respuestas para el código de error 200. ¿Esto significa que uno tiene que usar "predeterminado" para todas las respuestas de error, y solo se puede tener una estructura única para todas las respuestas erróneas, o hay una manera de especificar que ciertos atributos son opcionales en las definiciones?

Answer 1

Está recibiendo el error en el modelo, porque esa no es la forma de definir las propiedades requeridas.

La forma correcta sería:

    "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"
            }
        }
    }

Cualquier cosa que no esté en la propiedad required se supone que es opcional. Tenga en cuenta que esto implica que es posible obtener tanto el message como el filename .

A continuación, puede utilizar este modelo para su respuesta 200.

Sin embargo, cuando se trata del diseño de API REST, esto rompe uno de los estándares más comunes. Los códigos de estado, tomados del protocolo HTTP están destinados a transmitir el resultado de la operación. 2XX se usan para respuestas exitosas, 4XX son para errores debidos a una entrada incorrecta del usuario, 5XX son para problemas en el lado del servidor (3XX son para redireccionamientos). Lo que está haciendo aquí es decirle al cliente: la operación fue exitosa, pero de hecho, puede ser un error.

Si aún puede modificar la API, le recomiendo que haga esa distinción utilizando los códigos de estado, incluso utilizando las distinciones afinadas, como 200 para una operación GET exitosa, 201 para la operación POST (o creación) exitosa, etc. sobre las definiciones aquí - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html .