Use names for query string parameter examples

[waldyrious]

The support for query string examples introduced in 9f2fa93 as a fix to #269 seems to use the value of the examples, rather than the name (if they have one, e.g. when using examples instead of example).

For instance, say I have this parameter:

parameters:
  - name: q
    in: query
    description: A search query to filter the returned items
    schema:
      type: string
    examples:
      'Filter by prefix':
        value:
          prefix:foobar
      'Limit number of returned items':
        value:
          limit:20

Here's what RapiDoc shows:

And here's what I'd expect to see instead:

(Especially since the content of the example is already shown in the text box, so it's just redundant to show it also in the link label.)

I realize that the examples added in 9f2fa93 use generic names like example1, example2, etc., but since the examples field of OpenAPI parameter objects contains a map, where the keys can be arbitrary strings, it would make sense to assume the names are semantically valid.

[mrin9]

but since the examples field of OpenAPI parameter objects contains a map, where the keys can be arbitrary strings, it would make sense to assume the names are semantically valid.

I dont think that would be a correct assumption to make.
If the intention is to have an explanation for the example then it should be done using the dedicated summary or description field for this, not using the keys http://spec.openapis.org/oas/v3.0.3#example-object

so the above spec can be re-defined as

parameters:
  - name: q
    in: query
    description: A search query to filter the returned items
    schema:
      type: string
    examples:
      example1:
        value:
          prefix:foobar
       summary: Filter by prefix
      example2:
        value:
          limit:20
        summary: Limit number of returned items

And you should see the desired result

To see it in action checkout the below example
https://mrin9.github.io/RapiDoc/examples/examples-multiple.html#get-/multiple-examples-in-query-param

(Especially since the content of the example is already shown in the text box, so it's just redundant to show it also in the link label.)

as I explained above we do show the example-summary if it exist else fallback on example-value however this behavior may change based on user feedbacks we are receiving

• When multiple examples are present we do not show all the values as only one text-box is available, so it wont be redundant to switch to values
• our UX team found that it leads to more confusion as the user needs to find the actual value of the example by clicking on it and watching the textbox. It is also an discoverability issue
• The suggestion from UX is to always show the actual value of example, and upon hovering, show example-summary
• At present RapiDoc ignores example-description as it can contain markdown syntax whereas in RapiDoc it is always shown as clickable-links. switching to values and hover-popup will open up the possibility to use description with markdown syntax

I will leave this issue open for a while, if you or others want to add any comments/suggestion

[waldyrious]

Ah, thanks — It didn't occur to me to try the summary field instead of the description. I do think that the fallback to the link label (when a summary isn't present) should be the example's key, rather than the raw value. Or at least, show both, if there's a concern about discoverability (although I don't see why that would be problematic when using the key, but not when using the summary).

Showing the description in rich text as a pop-up would also be a good solution IMO. Completely ignoring the description certainly isn't right.

Thanks for the quick and detailed feedback.

[mrin9]

if there's a concern about discoverability (although I don't see why that would be problematic when using the key, but not when using the summary).

well, discoverability is an issue weather we use summary , description or anything else thats why I said we may be changing this behavior and just use the raw value. For now we are waiting to complete our user survey round, most have complained about it being confusing or hides the real data.

Going back on the original issue that use key if summary or description isn't present, most in our team thinks falling back on raw value is more accurate. There isn't anywhere in the spec mentions that keys can some-how be related at best it can be a practice adopted by some. Just to provide you another aspect, we have users who would auto generate specs and the examples gets sequence # like key, it would be real annoying for them to show keys instead of the actual value.

I am closing this issue now. If you are still not satisfied with the explanation feel free to open a new one. provide us with some use cases or any widely adopted practice and we may take it back to our design boards