Examples for enum Choices

[BostonKevin]

When using the Swagger Editor, and specifying a set of choices for a parameter with enum, it is not possible to specify examples for each enum value.  While this kind of situation my not frequently arise, it has occurred in the REST API that I am currently documenting. In this API, it is possible to pass either an email address or a user key as a URL parameter to retrieve information on a particular user.  The syntax for the call would be as follows:

curl -X GET "https://dev.test.com/xapis/User/first_key" -H  "accept: application/json"

where first_key might be either an email address or a user key.

It is possible to document this kind of syntax in the Swagger Editor, as follows:

  '/fsfd/User/{first_key}':
    get:
      tags:
        - User
      summary: Retrieve information on a user.
      description: 'Use GET to retrieve information on a user. To do this, specify the user key immediately after /xapis/User/.'
      parameters:
        - name: first_key
          in: path
          description: A user key must be specified when you use GET.
          required: true
          style: simple
          explode: false
          schema:
            enum:
              - user_key
              - email_address
            type: string

It is possible to select either user_key or email_address on the drop down, as shown in the screen shot, but it is not possible to specify an example to be inserted when either user_key or email_address is selected on Swagger Inspector and a user tries out the syntax.

Is there any way - perhaps outside of Swagger Editor itself - to specify examples for enum values?

Thanks!

Kevin

[HKosova]

Hi Kevin,

An enum specifies the actual values for a parameter, so your definition means that the URL can be literally either
/fsfd/User/user_key
or
/fsfd/User/email_address

Could you please provide some examples of how the actual URLs look like?

Do they look like this?

https://dev.test.com/xapis/User/abcde123545
https://dev.test.com/xapis/User/user@example.com

[BostonKevin]

Yes, that is exactly how the different choices work.

The example thta I already presented is as close to the actual API as I could give in a public forum.

Thanks,

Kevin

[HKosova]

It can be defined as follows:

  '/fsfd/User/{first_key}':
    get:
      tags:
        - User
      summary: Retrieve information on a user.
      description: 'Use GET to retrieve information on a user. To do this, specify the user key or email address immediately after /xapis/User/.'
      parameters:
        - name: first_key
          in: path
          description: A user key (for example, _abcde12345_) or email address (for example, _user@example.com_).
          required: true
          schema:
            type: string
          example: 'user@example.com'

          # Or with multiple examples
          # (but this is not supported in Swagger UI and Editor yet)
          # examples:
          #    user_key:
          #      summary: Example of a user key
          #      value: abcde12345
          #    email_address:
          #      summary: Example of an email address
          #      value: 'user@example.com'

[BostonKevin]

Thanks for the prompt reply.  I will use the proposed workaround that you have provided but it is shame that something similar does not work with enum.

[BostonKevin]

Would you know if or when Swagger Editor or Swagger UI will support the use of enum in the way described earlier?

This cannot be the first time that two different parameters may be inserted in the same position in a URL path.

Thanks!

Kevin

[RonRatovsky]

Hi Kevin,

As Helen explained, enums represent the actual literal values that are valid to that parameter, and they cannot be used to specify two different input types. Enum does not affect the type of the value, but the actual literal value of the parameter.

In OAS3, you can specify multiple parameter values using oneOf.

[BostonKevin]

It seems that oneOf can be used to validate data passed in a payload. Can it also be used to specify one of two distinct and mutually exclusive URL parameters?

[RonRatovsky · Accepted solution]

No, there's no way to describe mutually exclusive parameters.