Forum Discussion

BostonKevin's avatar
BostonKevin
Contributor
6 years ago

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

 

  • RonRatovsky's avatar
    RonRatovsky
    6 years ago

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

  • HKosova's avatar
    HKosova
    SmartBear Alumni (Retired)
    6 years ago

    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's avatar
      BostonKevin
      Contributor
      6 years ago

      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's avatar
        HKosova
        SmartBear Alumni (Retired)
        6 years ago

        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'