Allow 'examples' for the whole operation

[jugaadi]

Current examples are described in the media-type and schema object. Since request, response and params(including content-type) are decoupled, there is no way to map the response example with the corresponding param and request example.

If examples can be described for the whole operation, it would be easy to write less ambiguous examples and document the API better. Tools like doc generator, mock servers, etc could benefit a lot from this design. Furthermore, even test cases can be generated or run directly based on these documented examples.

PS: We currently resolve this using a unique identifier for each example and stating the purpose in yaml comments.

[darrelmiller]

We discussed this in the TDC call on Oct 27th. Some questions:

• Do we need to define a JSON/YAML structure for representing request & response?
• Is there a difference between these examples and a HTTP "test suite" for the API?
• Should this be additive to just response examples or be a replacement?

Suggestion: dictionary of examples at the request level that contains request and corresponding response examples. Then have singular example property for response objects.

[jugaadi]

1. Yes. Any other alternative?
2. A separate document along the lines of overlay would be better suited for this purpose. This document could be $ref'ed in the operation object via samples key. This can avoid breaking changes to the spec and at the same time, the sample file can be separately verified via the spec it refers.
3. Wouldn't suggest making any changes in the current spec.

[handrews]

See #90 (comment) for more discussion (but keep future discussion here).

A particularly interesting point from @mikekistler is a way to use naming conventions in existing Example Objects to accomplish this, and the idea that we could highlight this in the spec:

I think that you can use named examples to link together example parameter values, request body, and response body -- forming a cohesive operation example.

For example, you can define an example with the name "Create a foo" (in examples) for appropriate parameters, the request body and the response body. Taken together, these can be considered a cohesive example for "Create a foo".

[handrews]

See also OAI/OpenAPI-Specification#859 and OAI/OpenAPI-Specification#3874 ... I should really consolidate these further.