Add example/s as "Operation Request" child

[chatelao]

To define valid parameter combination examples, it would be nice to define consistent examples for an operation and not only on JSON / single-parameter base.

The alternative to use the same Id on every example is less intuitive, especially when reusing type definitions of parameters

[MikeRalphson]

Could you show an example of what you'd like to be able to do to clarify your question?

[hkosova]

I think the OP is asking for the ability to provide examples for different combinations of parameters. Maybe even a combination of parameters + request body.

Consider an item search operation that supports pagination and sorting:

paths:
  /items:
    get:
      parameters:
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
            minimum: 0
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 0
            maximum: 50
            default: 20
        - in: query
          name: sort
          schema:
            type: string
            enum: [asc, desc]
            default: asc
        - in: query
          name: sort_by
          schema:
            type: string
            enum: [name, created]
            default: name

As a technical writer, I would like to provide examples for:

• get the first 50 items: ?limit=50
• get items 20-29: ?offset=19&limit=10
• get the last created item: ?sort=desc&sort_by=created&limit=1

As a user of an interactive API console, I would like to use these examples to fill in the corresponding values for multiple parameters at once.

The current workaround is to add such examples to the operation description.

[a-akimov]

We experience the same problem. We've started added more and more examples to the OpenAPI files themselves (e.g. see https://github.com/Adyen/adyen-openapi/blob/master/json/CheckoutService-v67.json#L8178-L8936), but not clear how to give examples for GET.

Of course, there shouldn't be request body for GET but we still want to show examples of GET URLs (and possible responses for these comibations of query parameters).

[judielaine]

Please see my whiny Stack Overflow Q&A for another use case: https://stackoverflow.com/questions/68748714/how-to-specify-an-example-of-two-path-template-parts-in-openapi-swagger/68748715#68748715

[handrews]

This is another issue that would be solved by #1502.

[hkosova]

Related: #859