Xác định thuộc tính có kiểu dữ liệu hỗn hợp trong Swagger

Question

Tôi đã có một tài liệu vênh vang làm việc để tạo tài liệu bằng cách sử dụng dự án Swagger-UI, nhưng tôi đang gặp sự cố nhỏ.

Mongoose hỗ trợ kiểu dữ liệu Mixed, cơ bản là đối tượng không có cấu trúc có thể chứa bất kỳ thứ gì. Tuy nhiên, theo đặc điểm của Swagger, các giá trị duy nhất có thể có của một thuộc tính là type là string, integer, number, boolean và array. Tôi đã không thể tìm thấy bất cứ điều gì trong tài liệu, trên Google, hoặc trong các vấn đề mở cho dự án Swagger-Spec trên GitHub mà sẽ cho phép các loại dữ liệu hỗn hợp.

Trong tài liệu Swagger-Spec, nơi chúng xác định các tùy chọn type, chúng tham chiếu đến dự án JSON-Schema. Theo đặc tả JSON-Schema object phải là một tùy chọn, nhưng nó không được liệt kê như là một giá trị tiềm năng trong Swagger-Spec.

Có ai biết cách chỉ định trong tài liệu Swagger rằng thuộc tính của mô hình có thể chứa bất kỳ giá trị nào (giá trị nguyên thủy đơn lẻ hoặc đối tượng) không?

Ví dụ

định nghĩa schema Mongoose:

var sampleSchema = new mongoose.Schema({ 
    lookupCodes : { type: [mongoose.Schema.Types.Mixed] }, 
    address: { type: mongoose.Schema.Types.Mixed } 
}); 

mongoose.model('Sample', sampleSchema); 

Sử dụng mô hình cầy mangut:

var Sample = mongoose.model('Sample'); 
var doc = new Sample(); 

Đây là tất cả các giá trị hợp lệ cho hai thuộc tính định nghĩa:

doc.lookupCodes = ['A', 'B', 3, 4, 5, 'F']; 

doc.lookupCodes = ['A', { code: '123' }, 5]; 

doc.address = '123 Main St., San Jose, CA, 95125'; 

doc.address = { street: '123 Main St.', city: 'San Jose', state: 'CA', postalCode: '95125'} 

Swagger 1.2 tài liệu (đoạn mã):

"models": { 
    "Sample": { 
     "properties": { 
      "lookupCodes": { 
       "type": "array", 
       "items": { 
        "type": "??????" 
       }, 
       "description": "An array of lookup codes. Codes can be strings, numbers or an object containing the `code` property." 
      }, 
      "address": { 
       "type": "??????", 
       "description": "An address. This value can be a single string, containing all the elements of the address together, or it can be a structured object with each of the elements as separate properties of the object." 
      }, 

Tôi chỉ đơn giản là tìm kiếm một cách để cho các nhà phát triển xem tài liệu biết rằng một tài sản cụ thể trong một mô hình có thể chấp nhận/trả lại bất kỳ giá trị (biến nguyên thủy hoặc một đối tượng).

Answer 1

Trong câu hỏi của bạn, bạn mô tả hai trường hợp sử dụng riêng biệt.

Đầu tiên là sử dụng mảng có giá trị hỗn hợp và trường thứ hai là trường cụ thể có thể có bất kỳ giá trị nào (có thể là đối tượng, nguyên thủy và có khả năng là mảng).

Chuyển đổi một cách rõ ràng không hỗ trợ mô hình như vậy. Có một số lý do cho nó, nhưng họ tập trung vào quyết định và hỗ trợ ngôn ngữ. Mặc dù ngôn ngữ động có thể dễ dàng hỗ trợ các API không xác định và các ngôn ngữ đánh máy yếu có thể dễ dàng hỗ trợ các loại động, các ngôn ngữ khác sẽ chịu đựng nó. API có nghĩa là khả năng tương tác, độc lập với ngôn ngữ, vì vậy bạn phải xem xét những hạn chế này.

Trong khi Swagger có nghĩa là một công cụ tài liệu, hệ sinh thái công cụ của nó bao gồm các giải pháp cần có khả năng sản xuất và tiêu thụ các API như vậy trong hầu hết mọi ngôn ngữ. Rõ ràng, nó không thể có độ bao phủ 100%, nhưng nó cố gắng tránh các vấn đề đã biết.

Swagger 2.0 bổ sung tính linh hoạt hơn nhiều trong việc xác định các mô hình, cho phép các đối tượng dạng tự do (và ghi chú - đối tượng, không phải nguyên thủy).Mặc dù nó không được khuyến khích sử dụng nói chung, có những trường hợp sử dụng mà không thể tránh được, nhưng ngay cả những ngôn ngữ mạnh có thể xử lý được (tôi có thể giải thích về các trường hợp sử dụng, nhưng nó không liên quan đến câu hỏi tại tay).

Như thông tin bổ sung - hãy nghĩ về thông tin đó từ quan điểm tài liệu và tôi sẽ sử dụng trường address làm ví dụ. Những gì bạn đang nói ở đây, API Wise, là trường địa chỉ là ký tự đại diện hay không. Bạn có thể chấp nhận mọi thứ cho nó và không phải là địa chỉ, không phải có cấu trúc, không cần phải có thông tin cụ thể. Nếu ai đó muốn, họ có thể sử dụng trường đó để lưu trữ mã khởi chạy hạt nhân. Bây giờ, nếu đây là ý định của bạn, thì chỉ cần đánh dấu trường là một giá trị chuỗi và nếu ai đó muốn gửi một đối tượng JSON được tuần tự hóa dưới dạng một chuỗi, nó cũng sẽ phù hợp.