search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.55k stars 9.05k forks source link

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

Open amarzavery opened 7 years ago

amarzavery commented 7 years ago

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.

amarzavery commented 7 years ago

/cc @darrelmiller

darrelmiller commented 7 years ago

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/http text format.

I do agree that being able to present a more complete request/response example would be beneficial.

ckriley commented 7 years ago

Examples is definitely an area that needs improvement and developers we work with would prefer wire format per @darrelmiller.

chatelao commented 3 weeks ago

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.