多态性中的“鉴别器”，OpenAPI 2.0（Swagger 2.0）

Question

引用OpenAPI 2.0，Schema Object，或Swagger 2.0，Schema Object，

discriminator

字段的定义为：

添加对多态性的支持。鉴别器是架构属性名称，用于区分继承该架构的其他架构。使用的属性名称必须在此模式中定义，并且必须位于

required

属性列表中。使用时，该值必须是该模式或继承它的任何模式的名称。

我的困惑/问题：

• 我不清楚它在继承或多态性中到底扮演什么角色。有人可以用一个工作示例来解释一下

  discriminator

  吗？它到底是做什么的，如果我们不使用它怎么办？有任何错误、警告或某些操作依赖于它的工具吗？
• 是否是swagger-editor不支持

  discriminator

  ，并且该字段在其他一些工具中使用？

到目前为止我尝试过的：

• 我尝试使用 swagger-editor 和同一文档中的示例（也在下面提到）来尝试这个属性，看看我是否可以看到它的任何特殊行为。我更改了属性，将其删除，并将

  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

根据这个 google group，

discriminator

用于

allOf

属性之上，并且它是在多态性的超类型中定义的。如果不使用

discriminator

，则

allOf

关键字描述一个模型包含其他模型的组合属性。

就像在示例代码中一样，

Pet

是一个超类型，其属性

petType

被标识为

discriminator

，而

Cat

是

Pet

的子类型。以下是

Cat

对象的 json 示例：

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

使用

discriminator

旨在指示用于标识对象类型的属性。假设有工具可以正确支持使用

discriminator

定义对象，则可以通过扫描属性来确定类型。例如根据

Cat

识别物体是

petType

。

但是，当前版本的规范或示例中没有明确定义

discriminator

字段（请参阅 issue #403）。据我所知，Swagger目前还没有提供合适的工具来支持它。

如果模型具有用于确定类型的属性，则可以使用

discriminator

。这种情况下就自然适合了，可以作为其他开发者理解多态关系的指标。如果考虑像ReDoc这样支持

discriminator

的第三方工具（请参阅此

gif

中的petType和示例），您可能会发现这很有用。

Answer 2

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

（我知道您确实询问过有关 OpenApi 2 的问题，但 OpenApi 3 中对此有了很大改进，希望您可以利用它）。

请参阅：https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#discriminator-object了解 v3.0.0 规范