25

引用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
4

2 回答 2

13

根据这个google group，discriminator在属性之上使用allOf，它在多态的超类型中定义。如果discriminator不使用，则allOf关键字描述一个模型包含其他模型的属性以进行组合。

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

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

使用discriminator意图表示用于标识对象类型的属性。假设有工具可以适当地支持定义对象的使用discriminator，则可以通过扫描属性来确定类型。例如，识别对象是一个Cat根据petType。

但是，discriminator当前版本的规范或示例中没有很好地定义该字段（参见问题 #403）。据我所知，目前没有 Swagger 提供的工具可以正确支持它。

discriminator如果模型具有用于确定类型的属性，则可以使用。这种情况下自然契合，可以作为其他开发者理解多态关系的指标。如果考虑支持（参见此gif和示例）的ReDoc等第三方工具，您可能会发现这很有用。discriminatorpetType

于 2016-09-27T16:52:46.617 回答
6

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

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

有关v3.0.0 规范，请参阅：https ://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject

于 2017-09-27T21:20:53.133 回答