3

I am trying to work out if there is a concise way to describe my API using OpenAPI v3+, where I have a response object containing multiple properties, of which some are mutually exclusive and required.

For example, suppose I have an API that always returns an 'id' but then depending upon the type of resource will always additionally return one and only one other property (e.g. 'apple' or 'orange' but never both).

In similar questions around query parameters, I have seen solutions involving usage of min/maxProperties and oneOf (e.g. How to define mutually exclusive query parameters in Swagger (OpenAPI)?). However I don't believe I can use min/maxProperties, because that could lead two mutually exclusive objects being returned, and the use of oneOf seems verbose as you end up specifying the same properties multiple times as per this example (which I think works but seems awkward):

    schema:
      type: object
      oneOf:
        - require: [id, apples]
          properties:
            id:
              type: integer
              example: 123
            apples:
              type: string
              example: test
        - require: [id, oranges]
          properties:
            id:
              type: integer
              example: 123
            oranges:
              type: string
              example: test

Am I missing an obvious solution or is this the only way of doing this?

markus02
  • 43
  • 4
  • See also https://stackoverflow.com/questions/55615638/mutually-excluding-properties-in-swagger – Raedwald Mar 18 '22 at 10:29
  • 1
    Thanks @Raedwald, I think I came across similar answers on the web which seemed to suggest using oneOf and required, but the think I think it misses is that required does not exclude the provision of other properties and therefore in that linked example you could still provide property_1 and property_2, unless I have misunderstood? – markus02 Mar 30 '22 at 09:46

0 Answers0