我正在使用 Swagger 2.0 来定义我们的 API 契约模式,我们计划在其中使用带有判别器的多态性。我现在有一个父类(名为 Animal)和两个扩展 Animal 的子类(狗/猫)。 Animal 将有一个 AnimalType 字段,用于识别动物类类型。我想要多种动物类型,如“狗”、“猫”、“马”、“牛”,并且动物类型和模型之间的映射如下 -
狗 -> 狗
猫 -> 猫
马 -> 动物
牛 -> 动物
如果没有为动物类型马/牛定义模式,则默认情况下会选择动物。我的理解正确吗?
如果以下架构有效,有人可以帮忙吗?或者我将如何使其工作?
下面是我正在尝试创建但无法在 swagger 2.0 编辑器中测试的架构,因为它不支持鉴别器 - https://editor.swagger.io/?url=https://raw.githubusercontent.com/ OAI/OpenAPI-规范/main/examples/v2.0/yaml/api-with-examples.yaml
components:
schemas:
Animal:
type: object
required:
- animalType
properties:
animalType:
type: string
enum:
'Dog'
'Horse'
'Cow'
'Cat'
name:
type: string
discriminator:
propertyName: animalType
Cat:
- allOf:
- $ref: '#/components/schemas/Animal'
- type: object
# all other properties specific to a `Cat`
properties:
color:
type: string
- x-ms-discriminator-value: 'Cat',
Dog:
- allOf:
- $ref: '#/components/schemas/Animal'
- type: object
# all other properties specific to a `Dog`
properties:
bark:
type: string
x-ms-discriminator-value: 'Cat'
鉴别器概念的存在是为了帮助处理需要解析符合 OpenAPI 规范的实例数据的软件,例如验证器、序列化器,以及较小程度的代码生成器,使用模式构造 oneOf、anyOf 和全部。
使用这些构造定义的 OpenAPI 模式类型对于处理器来说很难使用,因为在它们下定义的 子模式 通常非常不同,并且为了在遇到潜在一致的数据时确定适当的子模式,有必要一项一项地尝试,直到找到匹配项。鉴别器允许 OpenAPI 规范作者通过在符合数据上定义显式值匹配来确定要使用的相关子模式来规避此问题,这很棒!
但是,处理器只会尊重明确定义的子模式。如果微分值指示应该使用一个子模式,但结果发现该子模式不存在,那么您的average
处理器将简单地陷入混乱的堆中,而不是开始“发明”子模式,并且无论实际实现如何,我们当然不应该有这样的期望。如果没有为动物类型马/牛定义模式,则默认情况下会选择动物。我的理解正确吗?
模型即可。这是一个相当冗长的方式来表达两件事:不,你对鉴别器如何工作的期望是不正确的,其次,在你的 API 边界上公开多态行为的愿望应该被缓和,因为你应该理解这会让你的API 的设计比它需要的要复杂得多;在绝大多数用例中,您只需要简单的
单态