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.

Inizia leggendo documentation/x-ms-examples.md e il file schema/example-schema.json collegato per comprendere gli esempi proposti a livello di operazione e l’estensione esistente. La issue è una proposta della community, non un’attività di implementazione; per considerarla completata sarebbe necessario raggiungere un accordo su se e come questo approccio debba rientrare nella OpenAPI Specification.