Swagger - Xác định tài sản đối tượng bắt buộc hoặc Nhiều Responses

Question

Tôi có một API mà một trong hai trả về phản ứng sau đây về thành công:

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

hoặc một cái gì đó giống như dưới đây khi thất bại:

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

Thuộc tính filename là chỉ được chỉ định nếu yêu cầu thành công, nhưng một thông báo được cung cấp nếu có lỗi. Điều này có nghĩa là thông báo và các thuộc tính tên tệp là "tùy chọn" nhưng yêu cầu thuộc tính kết quả.

tôi đã cố gắng xác định đối tượng phản ứng này trong một định nghĩa như hình dưới đây:

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

Nhưng nó xuất hiện vênh vang mà không thích "yêu cầu" thuộc tính và sẽ hiển thị thông báo lỗi sau:

Khi tôi xem ví dụ từ việc vênh vang, chúng có bố cục sau đây, trong đó có hai định nghĩa phản hồi khác nhau thay vì một.

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

Tôi có thể làm điều này, nhưng có vẻ như không thể có nhiều câu trả lời cho mã lỗi 200. Điều này có nghĩa là người ta phải sử dụng "mặc định" cho tất cả các phản hồi lỗi, và người ta chỉ có thể có một cấu trúc duy nhất cho tất cả các câu trả lời sai, hoặc có cách nào để xác định rằng các thuộc tính nhất định là tùy chọn trong định nghĩa?

Answer 1

Bạn đang gặp lỗi trong mô hình, vì đó không phải là cách để xác định các thuộc tính bắt buộc.

Hình thức đúng sẽ là:

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

Bất cứ điều gì không nằm trong bất động sản required được giả định là không bắt buộc. Lưu ý rằng điều này ngụ ý rằng bạn có thể nhận được cả haimessage và filename.

Sau đó, bạn có thể sử dụng mô hình này cho 200 phản hồi của mình.

Tuy nhiên - khi nói đến thiết kế REST API, điều này sẽ phá vỡ một trong các tiêu chuẩn phổ biến hơn. Các mã trạng thái, được lấy từ giao thức HTTP có nghĩa là truyền đạt kết quả của hoạt động. 2XX được sử dụng để trả lời thành công, 4XX là do lỗi do đầu vào người dùng kém, 5XX là các vấn đề ở phía máy chủ (3XX là dành cho chuyển hướng). Những gì bạn đang làm ở đây, là nói với khách hàng - hoạt động đã thành công, nhưng trên thực tế, nó có thể là một lỗi.

Nếu bạn vẫn có thể sửa đổi API, tôi khuyên bạn nên tạo sự khác biệt bằng cách sử dụng mã trạng thái, thậm chí sử dụng phân biệt được tinh chỉnh như 200 cho hoạt động GET thành công, 201 cho hoạt động POST (hoặc tạo) thành công và cứ như vậy, dựa trên các định nghĩa ở đây - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.