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.