Proposal: Having an example for an entire operation in one place (request + response)

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.

Start by reading documentation/x-ms-examples.md and the linked schema/example-schema.json to understand the proposed operation-level examples and existing extension. The issue is a community proposal rather than an implementation task; done would require agreement on whether and how this approach belongs in the OpenAPI Specification.