Swagger-ui: Display enums in parameter info

[hkosova]

| Q | A
| ------------------------------- | -------
| Bug or feature request? | Feature request
| Which Swagger/OpenAPI version? | 2.0, 3.0
| Which Swagger-UI version? | 3.4.3
| How did you install Swagger-UI? | http://editor.swagger.io
| Which browser & version? | N/A
| Which operating system? | N/A

Demonstration API definition

2.0:

swagger: '2.0'
info:
  title: test
  version: 0.0.0
paths:
  /report:
    get:
      parameters:
        - in: query
          name: rel_date
          required: true
          type: string
          enum:
            - today
            - yesterday
            - lastweek
      responses:
        200:
          description: OK

3.0:

openapi: 3.0.0
info:
  title: test
  version: 0.0.0
paths:
  /report:
    get:
      parameters:
        - in: query
          name: rel_date
          required: true
          schema:
            type: string
            enum:
              - today
              - yesterday
              - lastweek
      responses:
        '200':
          description: OK

Expected Behavior

The parameter info in the UI displays the enum values.

Current Behavior

The enum values are only displayed when we do "try it out" and are not displayed normally.

Context

Related to #3518.

[feenr]

I'm interested to take up this issue.

[webron]

@feenr This one is a bit trickier. The issue itself is broader and the solution should be different than what's suggested in the main ticket. If you're willing to explore it, I'll be happy to dive into details.

[feenr]

I'm still interested. This is a feature I wanted in my own use. Please share any details about the expected behavior.

[feenr]

Parameter display seems like it could use a bit of design love and this only makes it worse, but this is where I was at from just dropping in the existing enum component.

[webron]

Yeah, and that's one of the reasons it's not the best approach.

The proper approach would be to display the fields as they would be when the try it out is enabled, only show them in a disabled form. So you can still see the value, but not execute anything. Only when the try it out is enabled, the fields would become enabled as well.

[feenr]

When "try it out" is enabled it's a dropdown, which only really works for user input.

How about something like this?


If you're happy with that UX I can clean up the style a bit.

[webron]

Why does a drop down work only for user input? If a user can click it and see the available values, it's the same information.

[feenr]

When I said a dropdown won't work, I meant that usually dropdowns are used when a user is making a selection to perform an action. I can't think of anywhere which a drop down is used just to present a list of values.

If I were to come to this form and make a selection from the enum dropdown I'd expect some sort of interaction, like the the responses to update to reflect my selection. When "take action" is enabled a drop down makes sense because the user's selection is used when they press "execute"

All this being said, it shouldn't be much effort to add the drop down, and I can do that if it's the desired experience.

[alebar]

I agree with @feenr that dropdown is bot the beat to display value.

@feenr, please consider two more things:

• it is possibile to create parametr accepting an array od enums ( that's the case of API that we have at work).
• openapi spec allows to add description for each enum's value. This should be shown as well....

[alebar]

"bot the beat" came from mine's phone's dictionary. Sorry. I meant "not the best"

[feenr]

Did not know about the description for enum values. Thanks for sharing.

[hkosova]

openapi spec allows to add description for each enum's value. This should be shown as well....

@alebar do you mean schema-level descriptions like this?

components:
  schemas:
    Color:
      type: string
      description: >
        The color values are:
         * `r` = red, #ff0000
         * `g` = green, #00ff00
         * `b` = blue, #0000ff
      enum:
        - r
        - g
        - b

Parameters and schemas have description, but enum values themselves don't have description (there's a feature request about that).

[alebar]

@hkosova yes, that's what I mean. I saw it here: https://swagger.io/docs/specification/data-models/enums but I admit that I didn't read it carefully. You're right that this is not a separate description property. And in fact the whole thing seems more like a suggestion, not the specification.

So I guess there are two ways of treating this:
a) ignore the Swagger's suggestion to put value's definition into enum's description property, or
b) parse the description to search for value's definitions and handle them.

IMHO it seems that b) is not an option. I think it's better to wait for the mentioned feature request and then do it properly. Till that time we would only have a problem when someone will follow the suggestion and add the values into description. Then those values will appear twice: as list in description and in @feenr 's widget. But I guess that's not the big problem.

Thanks @hkosova for pointing that out.

[hkosova]

@webron @shockey This was implemented in 3.9.0, right? (via PR https://github.com/swagger-api/swagger-ui/pull/3977)

🎉

[shockey]

@hkosova looks like it!

Closing.

[shockey]

Reopening, as #3977 is limited to array item enum rendering.

H/t @webron for noticing this 🦅 👁

[dedece35]

hi @webron @shockey

my last PR will add enum rendering for other types items.
see my last modifications (waiting for your review :p ) : https://github.com/swagger-api/swagger-ui/pull/4191

[shockey]

Fixed by https://github.com/swagger-api/swagger-ui/pull/4191 :smile:

[lock[bot]]

Locking due to inactivity.

This is done to avoid resurrecting old issues and bumping long threads with new, possibly unrelated content.

If you think you're experiencing something similar to what you've found here: please open a new issue, follow the template, and reference this issue in your report.

Thanks!