cancel
Showing results for 
Search instead for 
Did you mean: 

Examples for enum Choices

SOLVED
Highlighted
Contributor

Examples for enum Choices

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

 

1 ACCEPTED SOLUTION

Accepted Solutions
Moderator

Re: Examples for enum Choices

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

8 REPLIES 8
Moderator

Re: Examples for enum Choices

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

Helen Kosova
SmartBear Technical Writer
________________________
Vote up helpful replies.
Accept this reply if you think it's the best solution to your question.
Contributor

Re: Examples for enum Choices

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

 

 

 

Moderator

Re: Examples for enum Choices

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'

Helen Kosova
SmartBear Technical Writer
________________________
Vote up helpful replies.
Accept this reply if you think it's the best solution to your question.
Contributor

Re: Examples for enum Choices

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.

Contributor

Re: Examples for enum Choices

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

Moderator

Re: Examples for enum Choices

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.

Contributor

Re: Examples for enum Choices

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?

Moderator

Re: Examples for enum Choices

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

New Here?
Join us and watch the welcome video:
API Testing Mistake #2
APITestingMistake#2
Top Kudoed Authors