闊歩オプションのオブジェクトのプロパティまたは複数の応答を指定し

Question

私が成功した場合に、次の応答を返すのいずれかのAPIを持っています要求が成功した場合にのみ指定されますが、エラーがあった場合にはメッセージが提供されます。つまり、メッセージとファイル名のプロパティは「オプション」ですが、結果プロパティは必須です。

以下に示すように、私は定義の中で、この応答オブジェクトを定義しようとした

：

"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からの例を見ると、1つではなく2つの異なる応答定義がある次のレイアウトを持っています。

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

私はこれを行うことができますが、200エラーコードに対して複数の応答を持つことはできません。これは、すべてのエラー応答に「デフォルト」を使用しなければならないこと、誤ったレスポンスに対して1つの構造しか持たないこと、または特定の属性が定義上オプションであることを指定する方法があることを意味しますか？

Answer 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をまだ変更できる場合は、正常なGET操作の場合は200、POST（または作成）操作の成功の場合は201などの細かい調整を使用しても、状況コードを使用して区別することを強くお勧めします。それで、ここの定義に基づいて - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html。