web-dev-qa-db-fra.com

Swagger - Spécifiez la propriété d'objet facultative ou plusieurs réponses

J'ai une API qui renvoie la réponse suivante en cas de succès:

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

ou quelque chose comme ci-dessous en cas d'échec:

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

La propriété filename n'est spécifiée que si la demande a réussi, mais un message est fourni en cas d'erreur. Cela signifie que le message et les propriétés de nom de fichier sont "facultatifs" mais que la propriété de résultat est obligatoire.

J'ai essayé de définir cet objet de réponse dans une définition comme indiqué ci-dessous:

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

Mais il semble que Swagger n'aime pas l'attribut "requis" et affichera le message d'erreur suivant:

enter image description here

Quand je regarde un exemple de swagger, ils ont la disposition suivante où il y a deux définitions de réponse différentes au lieu d'une.

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

Je pourrais le faire, mais il semble que l'on ne puisse pas avoir plusieurs réponses pour le code d'erreur 200. Cela signifie-t-il que l'on doit utiliser "par défaut" pour toutes les réponses d'erreur et que l'on ne peut avoir qu'une seule structure pour toutes les réponses erronées, ou existe-t-il un moyen de spécifier que certains attributs sont facultatifs dans les définitions?

swagger
29
Programster

Vous obtenez l'erreur dans le modèle, car ce n'est pas la façon de définir les propriétés requises.

La forme correcte serait:

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

Tout ce qui n'est pas dans la propriété required est supposé être facultatif. Gardez à l'esprit que cela implique qu'il est possible d'obtenir à la fois message et filename.

Vous pouvez ensuite utiliser ce modèle pour votre réponse 200.

Cependant - en ce qui concerne la conception de l'API REST, cela casse l'une des normes les plus courantes. Les codes d'état, extraits du protocole HTTP, sont destinés à transmettre le résultat de l'opération. 2XX sont utilisés pour les réponses réussies, 4XX sont pour les erreurs dues à une mauvaise entrée utilisateur, 5XX sont pour les problèmes côté serveur (3XX sont pour les redirections). Ce que vous faites ici, c'est dire au client - l'opération a réussi, mais en fait, ce peut être une erreur.

Si vous pouvez toujours modifier l'API, je vous recommande vivement de faire cette distinction en utilisant les codes d'état, même en utilisant les distinctions affinées telles que 200 pour une opération GET réussie, 201 pour une réussite POST ( ou création) et ainsi de suite, sur la base des définitions ici - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html .

45
Ron