I have been searching and don't find many examples or clear explanation about when to use allOf or oneOf in OpenApi 3.0.
What is the difference between the use of allOf with discriminator or oneOf?
My use-case is the following:
a device can't be created if no deviceType are defined. You should be able to create only "mobile device"/"pin device"/"beacon device" which contains the properties depending on their type and also the deviceId and name from the protocol.
For now I have implemented the allOf version, and it is working. But I wonder if it is exactly what I want.
Device:
type: object
required:
- id
- name
- deviceType
discriminator: deviceType
properties:
deviceId:
type: string
description: The id (UUID) of the device
readOnly: true
name:
type: string
description: The name of the device
deviceType:
type: string
description: The type of the device
enum:
- MobileDevice
- PinDevice
- BeaconDevice
mobileDevice:
allOf:
- $ref: '#/definitions/Device'
- required:
- platform
- deviceToken
- location
properties:
platform:
type: string
description: |
The platform of the device, this can be any string
representing the platform type, for instance 'iOS'
deviceToken:
type: string
description: |
The deviceToken is the device push notification token
given to this device by the OS, either iOS or Android for
identifying the device with push notification
services.
location:
"$ref": "#/definitions/Location"
pinDevice:
allOf:
- $ref: '#/definitions/Device'
- required:
- location
properties:
location:
"$ref": "#/definitions/Location"
beaconDevice:
allOf:
- $ref: '#/definitions/Device'
- required:
- uuid
- major
- minor
properties:
uuid:
type: string
description: |
The UUID of the beacon, the purpose is to distinguish iBeacons
in your network, from all other beacons in
networks outside your control.
major:
type: integer
description: |
Major values are intended to identify and
distinguish a group
format: int32
minimum: 0
exclusiveMinimum: false
maximum: 65535
exclusiveMaximum: false
minor:
type: integer
description: |
Minor values are intended to identify and
distinguish an individual
format: int32
minimum: 0
exclusiveMinimum: false
maximum: 65535
exclusiveMaximum: false
I want to achieve that I shouldn't be able to initialize a device without specifying a type and if it has a specific type it needs to have all the required properties.