"phân biệt" trong đa hình, OpenAPI 2.0 (Swagger 2.0)

Question

Tham khảo OpenAPI 2.0, Schema Object, hoặc Swagger 2.0, Schema Object, và định nghĩa của discriminator lĩnh vực như:

Thêm hỗ trợ cho đa hình. Dấu phân biệt là tên thuộc tính lược đồ được sử dụng để phân biệt giữa lược đồ khác kế thừa lược đồ này. Tên thuộc tính được sử dụng PHẢI được xác định tại lược đồ này và nó PHẢI nằm trong danh sách thuộc tính required. Khi được sử dụng, giá trị PHẢI là tên của lược đồ này hoặc bất kỳ lược đồ nào thừa hưởng nó.

nhầm lẫn của tôi/câu hỏi:

• Nó là mơ hồ đối với tôi, những gì vai trò chính xác của nó trong thừa kế hoặc đa hình. Có thể một số xin vui lòng giải thích discriminator với một ví dụ làm việc cho thấy những gì nó chính xác làm gì và những gì nếu chúng ta không sử dụng nó? Bất kỳ lỗi, cảnh báo hoặc bất kỳ công cụ nào phụ thuộc vào nó đối với một số hoạt động?
• Có phải trường hợp swagger-editor không hỗ trợ discriminator và trường này được sử dụng trong một số công cụ khác không?

Những gì tôi đã cố gắng cho đến nay:

• Tôi đã cố gắng sử dụng swagger-editor và ví dụ từ các tài liệu tương tự (cũng đề cập dưới đây), để chơi xung quanh với tài sản này để xem nếu tôi có thể thấy bất kỳ hành vi đặc biệt nào của nó. Tôi đã thay đổi thuộc tính, xóa nó và mở rộng mô hình Dog đến một cấp sâu hơn và cố gắng giống nhau trên mô hình phụ mới, nhưng tôi không thấy bất kỳ thay đổi nào trong bản xem trước của swagger-editor.
• Tôi đã thử tìm kiếm trực tuyến và các câu hỏi về lưu lượng truy cập đặc biệt, nhưng không tìm thấy bất kỳ thông tin liên quan nào.

Các mẫu mã tôi sử dụng để làm thí nghiệm:

definitions: 
    Pet: 
    type: object 
    discriminator: petType 
    properties: 
     name: 
     type: string 
     petType: 
     type: string 
    required: 
    - name 
    - petType 
    Cat: 
    description: A representation of a cat 
    allOf: 
    - $ref: '#/definitions/Pet' 
    - type: object 
     properties: 
     huntingSkill: 
      type: string 
      description: The measured skill for hunting 
      default: lazy 
      enum: 
      - clueless 
      - lazy 
      - adventurous 
      - aggressive 
     required: 
     - huntingSkill 
    Dog: 
    description: A representation of a dog 
    allOf: 
    - $ref: '#/definitions/Pet' 
    - type: object 
     properties: 
     packSize: 
      type: integer 
      format: int32 
      description: the size of the pack the dog is from 
      default: 0 
      minimum: 0 
     required: 
     - packSize 

Answer 1

Theo goggle group này, discriminator được sử dụng trên đầu trang của allOf tài sản và nó được định nghĩa trong các loại siêu cho đa hình. Nếu không sử dụng discriminator, từ khóa allOf mô tả rằng một mô hình có chứa các thuộc tính của các mô hình khác để tạo thành.

Giống như trong mã mẫu của bạn, Pet là một loại siêu với tài sản của petType xác định là discriminator và Cat là một loại phụ của Pet. Sau đây là một ví dụ json của một đối tượng Cat:

{ 
    "petType": "Cat", 
    "name": "‎Kitty" 
} 

Việc sử dụng discriminator dự định để chỉ ra tài sản sử dụng để xác định loại của một đối tượng. Giả định rằng có các công cụ có thể hỗ trợ các đối tượng định nghĩa thích hợp với việc sử dụng discriminator, có thể xác định loại bằng cách quét thuộc tính. Ví dụ: xác định đối tượng là Cat theo petType.

Tuy nhiên, trường discriminator không được xác định rõ trong thông số kỹ thuật của phiên bản hiện tại hoặc các mẫu (xem issue #403). Theo như tôi biết, không có công cụ được cung cấp bởi Swagger đúng cách hỗ trợ nó vào lúc này.

discriminator có thể được sử dụng nếu mô hình có thuộc tính được sử dụng để xác định loại. Trong trường hợp này, nó là tự nhiên phù hợp và nó có thể được sử dụng như một chỉ báo cho các nhà phát triển khác hiểu mối quan hệ đa hình. Nếu các công cụ của bên thứ ba như ReDoc hỗ trợ discriminator (xem petType trong số này gif và example) được xem xét, bạn có thể thấy điều này hữu ích.

Answer 2

Chức năng phân biệt đối xử đã được cải thiện nhiều trong OpenApi 3. Bây giờ bạn cung cấp đối tượng phân biệt chứa tên của thuộc tính phân biệt đối xử, cũng như ánh xạ các giá trị của thuộc tính đó tới tên lược đồ.

(Tôi nhận ra bạn đã hỏi về OpenApi 2, nhưng điều này được cải thiện rất nhiều trong 3 mà hy vọng bạn có thể tận dụng nó).

Xem: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject cho spec thực tế