OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
Add example/s as "Operation Request" child
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
Could you show an example of what you'd like to be able to do to clarify your question?
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.
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).
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
