多态性中的"鉴别器",OpenAPI 2.0(Swagger 2.0)

Question

引用OpenAPI 2.0,模式对象或Swagger 2.0,模式对象以及discriminator字段定义:

添加对多态性的支持.鉴别符是架构属性名称,用于区分继承此架构的其他架构.必须在此模式中定义使用的属性名称,它必须位于required属性列表中.使用时,值必须是此架构的名称或继承它的任何架构.

我的困惑/问题:

• 这对我来说是模棱两可的,它在继承或多态性中起到了什么样的作用.有人可以discriminator用一个工作实例来解释它究竟做了什么以及如果我们不使用它会怎样？某些操作依赖于它的任何错误,警告或任何工具？
• 是不是swagger-editor不支持discriminator,并且这个字段用于其他一些工具？

到目前为止我尝试了什么:

• 我试图使用swagger编辑器和相同文档中的示例(也在下面提到),来玩这个属性,看看我是否可以看到它的任何特殊行为.我更改了属性,删除了它,并将Dog模型扩展到更深层次并在新的子模型上尝试相同,但我没有看到swagger-editor预览中的任何更改.
• 我尝试在线搜索,特别是stackoverflow问题,但没有找到任何相关信息.

我用来做实验的示例代码:

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

根据这个谷歌组,discriminator在allOf属性的顶部使用它,并在超类型中定义多态.如果discriminator未使用,则allOf关键字描述模型包含其他组合模型的属性.

就像在您的示例代码中一样,Pet是一个超类型,其属性被petType标识为,discriminator并且Cat是子类型Pet.以下是Cat对象的json示例:

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

使用discriminator意图指示用于标识对象类型的属性.假设有一些工具可以使用适当的支持定义对象,discriminator可以通过扫描属性来确定类型.例如,Cat根据标识对象petType.

但是,该discriminator字段在当前版本的规范或样本中没有明确定义(参见问题#403).据我所知,目前Swagger没有提供适当支持的工具.

discriminator如果模型具有用于确定类型的属性,则可以使用.在这种情况下,它自然适合,它可以用作其他开发人员理解多态关系的指标.如果考虑像ReDoc这样支持的第三方工具discriminator(请参阅petType此gif和示例),您可能会觉得这很有用.

Answer 2

在OpenApi 3中，discriminator功能已得到很大改进。您现在提供了一个discriminator对象，其中包含discriminator属性的名称，以及该属性的值到架构名称的映射。

（我知道您确实询问过OpenApi 2，但是3中对它进行了很大的改进，希望您可以使用它）。

参见：https : //github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject了解实际规格