☰

Swagger - オプションのオブジェクトプロパティまたは複数の応答を指定する 質問する

tag-icon • tag-icon swagger
Swagger - オプションのオブジェクトプロパティまたは複数の応答を指定する 質問する

成功した場合に次の応答を返す API があります。

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

または失敗した場合は以下のようになります。

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

ファイル名プロパティは、リクエストが成功した場合にのみ指定されますが、エラーが発生した場合はメッセージが提供されます。つまり、メッセージとファイル名プロパティは「オプション」ですが、結果プロパティは必須です。

この応答オブジェクトを次のように定義してみました。

"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 は「必須」属性を好まないようで、次のエラー メッセージを表示します。

ここに画像の説明を入力してください

Swagger の例を見ると、1 つではなく 2 つの異なる応答定義がある次のレイアウトがあります。

"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 の設計に関しては、これは一般的な標準の 1 つに違反しています。HTTP プロトコルから取得されたステータス コードは、操作の結果を伝えるためのものです。2XX は正常な応答に使用され、4XX はユーザー入力の誤りによるエラーに使用され、5XX はサーバー側の問題に使用されます (3XX はリダイレクト用)。ここで行っていることは、クライアントに操作が成功したことを伝えていますが、実際にはエラーである可能性があります。

API を変更できる場合は、ここでの定義に基づいて、200 は GET 操作の成功、201 は POST (または作成) 操作の成功など、微調整された区別を使用して、ステータス コードを使用して区別することを強くお勧めします。http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html。

おすすめ記事