Allow providing sample requests and responses

Sometime it is handy to have sample request or response example. Working with integration of larger project SUPERHUB, we go from API design over samples, validating them and finally implementing. Samples are key component in communication about API.

Option “tree”: agreed tree structure with basePathExamples parameter

API declaration would get new attribute “basePathExamples”.

Default value for basePathExamples could be <basePath>/_examples

Real examples would be available at url build from <basePathExamples>/<resourcePath>/<operationNickname>/request/<requestExampleName> and similarly <basePathExamples>/<resourcePath>/<operationNickname>/response/<responseExampleName>

Option “index”: Index of sample files within agreed tree structure

Option “tree” has a disadvantage, that collecting all sample file names/urls might not be always easy or even possible. To resolve that, we would put into path <basePathExamples>/<resourcePath>/<operationNickname> a file called index.json. This would be an object with two properties requests and responses, each holding list of path names for sample request/responses. The path shall be relative to given directory with index.json file as it is easier to fill it in (e.g. using find) and also easy to check by using an editor (use gf in vim, standing for “go file” - you either succeed and see the sample file, or hit a problem, if the path is invalid). We could also completely relax from requirement to use names request or response for directories and leave it up to the developer.

Option “links”: Explicit links from operation items to examples

We could reuse the concept of basePathExamples above plus allowing two new attributes within operation objects.

exampleRequests would be a list of urls, pointing to request examples.

exampleResponses would be a list of urls, pointing to response examples.

However, as such an option seems too intrusive to me, I will not detail on it.

How to start

Starting with agreed tree structure shall be rather easy, as in the simplest situation (using agreed default value for basePathExamples), there is no need to modify any of existing structures.

Allowing non-default values for basePathExamples sounds practical to me and relatively easy.

If we feel a need to extend it, I would prefer the “index” solution as it is much less intrusive comparing “links” option.

How to follow up

(this is out of scope of this ticket)

Swagger UI showing sample files

Swagger UI shall be able to show sample requests and responses.

Test suite for evaluating sample files

Having all the information proposed at hand, we shall be able writing a test suite, which would detect following problems:

• operation without sample request (if relevant) and sample response
• sample requests and responses being invalid with respect to data structures defined in API Declaration.

[vad]

I don’t understand how to use this… I don’t see any reference in the specification

[darrelmiller]

@marians You can put an example on a schema that is used by a body parameter. So it is possible, but parameter objects do not support example objects directly in 2.0.