webentwicklung-frage-antwort-db.com.de

Swagger - Geben Sie eine optionale Objekteigenschaft oder mehrere Antworten an

Ich habe eine API, die bei Erfolg entweder die folgende Antwort zurückgibt:

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

oder so ähnlich wie unten bei einem Fehler:

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

Die Eigenschaft Dateiname wird nur angegeben, wenn die Anforderung erfolgreich war. Bei einem Fehler wird jedoch eine Meldung angezeigt. Dies bedeutet, dass die Eigenschaften message und filename "optional" sind, die Eigenschaft result jedoch erforderlich ist.

Ich habe versucht, dieses Antwortobjekt wie folgt in einer Definition zu definieren:

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

Es scheint jedoch, dass swagger das Attribut "required" nicht mag und die folgende Fehlermeldung anzeigt:

enter image description here

Wenn ich mir ein Beispiel von swagger ansehe, haben sie das folgende Layout, in dem es anstelle einer zwei verschiedene Antwortdefinitionen gibt.

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

Ich könnte dies tun, aber es scheint, dass man nicht mehrere Antworten für den 200-Fehlercode haben kann. Bedeutet dies, dass man "default" für alle Fehlerantworten verwenden muss und nur eine einzige Struktur für alle fehlerhaften Antworten haben kann, oder gibt es eine Möglichkeit anzugeben, dass bestimmte Attribute in Definitionen optional sind?

29
Programster

Sie erhalten den Fehler im Modell, da auf diese Weise die erforderlichen Eigenschaften nicht definiert werden können.

Die richtige Form wäre:

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

Alles, was nicht in der Eigenschaft required enthalten ist, wird als optional angenommen. Denken Sie daran, dass dies impliziert, dass es möglich ist, sowohl message als auch filename zu erhalten.

Sie können dieses Modell dann für Ihre 200 Antworten verwenden.

Wenn es jedoch um REST API-Design geht, bricht dies einen der allgemeineren Standards. Die aus dem HTTP-Protokoll entnommenen Statuscodes sollen das Ergebnis der Operation übermitteln. 2XX werden verwendet Bei erfolgreichen Antworten handelt es sich bei 4XX um Fehler aufgrund falscher Benutzereingaben, bei 5XX um Probleme auf der Serverseite (bei 3XX um Weiterleitungen). es kann ein fehler sein.

Wenn Sie die API dennoch ändern können, würde ich dringend empfehlen, diese Unterscheidung mithilfe der Statuscodes vorzunehmen, auch wenn die fein abgestimmten Unterscheidungen verwendet werden, z. B. 200 für eine erfolgreiche GET-Operation, 201 für eine erfolgreiche POST ( oder Erstellung) Operation und so weiter, basierend auf den Definitionen hier - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html .

45
Ron