0

I have this path GET /pricing/{product-line}/countries/{country-code}: where product-line is an enum string path parameter, composed of 2 values: product-A, product-B.

As part of the request I want to add a query parameter called includes, which is of type array and its elements are enum of type string. Both product-A and product-B have their own set of enum which are valid and exclusive to them e.g. includes=A,B,C,D, enum set valid for product-A and includes=F,G,H,I,J enum set valid for product-B.

What is a good way to achieve this with OpenAPI 3.x ?

I have tried the following,

        - name: includes
          in: query
          description: List of pricing components that are included in the response.
          style: form
          explode: false
          schema:
            anyOf:
            - $ref: '#/components/schemas/ListOfVerificationIncludes'
            - $ref: '#/components/schemas/ListOfVoiceIncludes'

where the schema pattern for both of these objects look very similar:

    ListOfVoiceIncludes:
      description: List of voice pricing components which will be used to retrieve pricing information for.
      type: array
      uniqueItems: true
      minItems: 1
      items:
        $ref: "#/components/schemas/VoiceIncludes"

and

    VoiceIncludes:
      description: Pricing component which will be used to retrieve pricing information for.
      type: string
      enum:
        - pstn
        - did
        - inapp
        - sip
        - features

I was thinking of breaking the includes into 2 different query parameters, voice-includes and verification-includes but I'm not sure how to achieve the mutual exclusivity between the path parameter and the query parameter, product-A works with includes-A and product-B works with includes-B.

C. Vasile
  • 1
  • 2

1 Answers1

0

OpenAPI doesn't have a great way to define mutually exclusive query params to a single endpoint, and also doesn't allow duplicate paths to define different behaviors in this way. You can definitely "make it work" but some tooling may not handle it correctly if you're using it for docs or codegen. see this answer for some inspiration https://stackoverflow.com/a/49199240/8564731

I haven't tried it myself, but I wonder if it may be possible to use if, then syntax which is fully supported in OpenAPI 3.1.x or later. Earlier versions of OpenAPI 3.0.x had no support for this keyword. I'll try to put something together when I get some time

Jeremy Fiel
  • 140
  • 10