Code samples versus body payloads

[dvh]

I think the x-code-samples are meant to help developers getting started with certain requests, right? If so, I find it confusing that these samples are rendered in the request samples area, which already contains the body payload. See http://rebilly.github.io/ReDoc/ for example. The 'Add a new pet to the store' call contains JSON, C# and PHP samples. However, JSON is the actual body which needs to be POSTed to the API, where the C# and PHP samples do something else. I'd expect that a sample code could also be added to a GET operation, describing how to create the actual call. Also I'd say that Open APIs native body parameters have a different behaviour than the x-code-samples extension. Any thoughts on this?

[RomanHotsiy]

This is basically done for economy of vertical space. + both JSON payload example and code samples are related to request.
Also, most likely the one who reads the code sample doesn't need payload sample and vice versa.

But layout is not fixed in stone :) so any suggestions about how to organise it better are welcome

[dvh]

I will think about it and come up with a suggestion ;)

But is it correct that code samples don't work for GET requests or am I doing something wrong?

[RomanHotsiy]

@dvh are you trying the code samples from demo page? They are just placeholders and are not supposed to work.
Probably I should add some comments saying this to avoid confusion...

[dvh]

No, I meant that code samples don't seem to work for GET operations, but that probably is fixed by issue #93.

[RomanHotsiy]

Yes, you're right. Fix should be easy so expect this in the next release.

[RomanHotsiy]

Fixed together with #93