Làm thế nào tôi có thể mô tả mô hình json phức tạp trong swagger

Question

Tôi đang cố gắng sử dụng Swagger để mô tả web-api tôi đang xây dựng. Vấn đề là tôi không thể hiểu làm thế nào để mô tả đối tượng json phức tạp?

Ví dụ, làm thế nào để mô tả các đối tượng này:

{ 
    name: "Jhon", 
    address: [ 
    { 
     type: "home", 
     line1: "1st street" 
    }, 
    { 
     type: "office", 
     line1: "2nd street" 
    } 
    ] 
} 

Answer 1

Được rồi, vì vậy dựa trên những ý kiến ​​trên, bạn muốn giản đồ sau:

{ 
    "definitions": { 
    "user": { 
     "type": "object", 
     "required": [ "name" ], 
     "properties": { 
     "name": { 
      "type": "string" 
     }, 
     "address": { 
      "type": "array", 
      "items": { 
      "$ref": "#/definitions/address" 
      } 
     } 
     } 
    }, 
    "address": { 
     "type": "object", 
     "properties": { 
      "type": { 
       "type": "string", 
       "enum": [ "home", "office" ] 
      }, 
      "line1": { 
       "type": "string" 
      } 
     } 
    } 
    } 
} 

Tôi đã thực hiện một vài giả định để làm cho mẫu phức tạp hơn một chút, để giúp đỡ trong tương lai. Đối với đối tượng "người dùng", tôi đã tuyên bố rằng trường "tên" là bắt buộc. Ví dụ: nếu bạn cũng cần địa chỉ là bắt buộc, bạn có thể thay đổi định nghĩa thành "required": ["name", "address"].

Về cơ bản, chúng tôi sử dụng một tập con của lược đồ json để mô tả các mô hình. Tất nhiên không phải ai cũng biết điều đó, nhưng nó khá đơn giản để học và sử dụng.

Đối với loại địa chỉ bạn có thể thấy, tôi cũng đặt giới hạn thành hai tùy chọn - nhà riêng hoặc văn phòng. Bạn có thể thêm bất kỳ thứ gì vào danh sách đó hoặc xóa hoàn toàn "enum" để xóa ràng buộc đó.

Khi "loại" thuộc tính là "mảng", bạn cần phải đồng hành cùng với "mục" tuyên bố loại nội bộ của mảng. Trong trường hợp này, tôi đã tham chiếu một định nghĩa khác, nhưng định nghĩa đó cũng có thể là nội tuyến. Nó thường dễ dàng hơn để duy trì theo cách đó, đặc biệt là nếu bạn cần định nghĩa "địa chỉ" một mình hoặc trong các mô hình khác.

Theo yêu cầu, phiên bản nội tuyến:

{ 
    "definitions": { 
    "user": { 
     "type": "object", 
     "required": [ 
     "name" 
     ], 
     "properties": { 
     "name": { 
      "type": "string" 
     }, 
     "address": { 
      "type": "array", 
      "items": { 
      "type": "object", 
      "properties": { 
       "type": { 
       "type": "string", 
       "enum": [ 
        "home", 
        "office" 
       ] 
       }, 
       "line1": { 
       "type": "string" 
       } 
      } 
      } 
     } 
     } 
    } 
    } 
}