Description
The current mechanism to provide examples for artifacts in a swagger spec is fragmented. It does not give the consumer an overview (or a bird's eye view) of an example to complete that operation successfully.
If the example object is opened up and can be provided per operation then this solves the problem. People can provide multiple examples (variations) for that operation. It can be very easily used for documenting and (live/mock) testing the API.
Please read the detailed proposal over here. Currently we have implemented an extension named "x-ms-examples" for our specs. The schema for this extension can be found here.
It would be nice to see what the community thinks about it and if it is possible to get this approach formally in the open api specification.