Repository navigation
Proposal: Having an example for an entire operation in one place (request + response) #859
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.
Activity
amarzavery commentedon Dec 23, 2016
/cc @darrelmiller
darrelmiller commentedon Jan 6, 2017
The V3 spec does provide the ability to specify multiple examples for request/response bodies using an array. However, there currently isn't a mechanism to provide a description for that example.
When it comes to providing a more holistic example, I'm not sure that inventing a new JSON structure for an example instance would be the way I would go. I think I would be more tempted to stick to the natural
message/httptext format.I do agree that being able to present a more complete request/response example would be beneficial.
ckriley commentedon Jan 26, 2017
Examples is definitely an area that needs improvement and developers we work with would prefer wire format per @darrelmiller.
chatelao commentedon Jun 14, 2024
The "HTTP ARchive (HAR)" is somehow the "instance brother" of OpenAPI.
https://w3c.github.io/web-performance/specs/HAR/Overview.html
Maybe reusing part for the example data structures could be an idea?
HAR can be captured directly in Webbrowsers "F12 is your friend". And there are libraries générating OpenAPI from HAR.
n.b.: HAR is well known in forensics to and "trial proved" for digital evidence.
apiarya commentedon Sep 13, 2024
👀 on it