Allow providing sample requests and responses

[vlcinsky]

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.

[Siva]

HI, I see this a very useful feature for our project documentation. Any idea when this can be included in the spec?

[fehguy]

We're working on this for the 2.0 spec right now.

[fehguy]

and thanks @vlcinsky for putting down all these thoughts.

[Siva]

Awesome. thanks! Any idea when 2.0 spec will be out?

[fehguy]

july :)

[Siva]

Hi, I wanted to ping and check on the status of 2.0 spec since we are getting near the end of july. Are you guys still planning on releasing this july? Appreciate your help.

BTW we already started using the spec recently. You guys are doing great job with spec and it really helped us a lot on documenting our services. great work. Kudos!!!

[fehguy]

Hi, we're just about there--might be a week behind but it's worth the wait.

[Siva]

Great thank you!!!

[webron]

This has been added to Swagger 2.0.

[vad]

I don't understand how to use this... I don't see any reference in the specification

[webron]

@vad - for responses, check out https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responseExamples. For requests, watch out for a more elaborate explanation in the upcoming weeks.

[gmannos]

@webron @vlcinsky - Any update for request example thing?
another question - is basePathExamples not going to be used now ? as i saw for response, example can be published in 'elements' filed of Response Object.

[Nouhi]

@fehguy is there any news regarding this issue it's seems to be closed but the functionality isn't available

[foragerr]

@webron @fehguy Any updates on request example documentation?

[webron]

@foragerr it's not supported explicitly at the current version but is under discussion for the next version. We introduced a vendor extension in swagger-ui to support it, but it's not an official part of the spec.

[foragerr]

Thanks @webron ! Is that how you do this?

What is the vendor-extension called?

[webron]

No, that's just derived from the 'example' in model definitions that exists today. For body parameters it is called x-examples, for others x-example.

[marians]

Just to get this right, describing request examples is not part of the 2.0 spec?

[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.