View Response Data in Documentation?

[insodoc]

View Response Data in Documentation?

[jozsefsallai]

Experimental support for example responses has been added. It features syntax highlighting too (though to be honest, I've only tested that with JSON 😅). It's now available in v0.3.0! Here's what it looks like:

All you have to do is to enclose the example response between <!-- RESPONSE --> and <!-- ENDRESPONSE --> tags. This only works with one example. Any other example responses will be ignored.

Any thoughts, ideas, suggestions about this implementation?

(cc @ZarifS @lramosduarte)

[jozsefsallai]

Yes, you can add as many as you want and you can also specify the status code (see: #16 (comment)).

However, the syntax is going to change in a future release (see #30).

[jozsefsallai]

@gschier Fair enough! I can see why this wouldn't be ideal, yeah.

@ZarifS I will research into ways to making this workable. Until I can come up with a better solution, a good workaround would be to include the example response in the description of the request.

[lramosduarte]

Thanks @jozsefsallai , i ll test this later.

It looks like very interesting

[jozsefsallai]

Hey! Thank you for the kind words! :)

At the moment, Insomnia export files don't contain the server response, so there isn't really a way to do this (well, apart from running the requests on runtime but that would make the page slow and it will probably not work every time)! Maybe if @gschier can make it so that the response will also be exported, I could make it work with the documenter. 👀

[gschier]

Would definitely be possible to implement in Insomnia but I'm not sure that's ideal. It seems like @ZarifS wants to be able to specify an example response manually?

[ZarifS]

Yes exactly! For example showcasing the JSON response that would be expected from doing a call with certain parameters.

Say "/get/users" -> shows a response on the documenter showcasing the response that would be expected like a json body of what the server would send back.

This way anyone looking at the documentation will also known what the response would look like, hence making developing with that API much easier in the case of mocking it for example.

[gschier]

I wonder if we could use HTML comments in the request description to designate that it's a response. Then documented could look for those comments and deal with them accordingly

[jozsefsallai]

Yeah, I was thinking of a similar implementation. 👍

[jozsefsallai]

Closing for inactivity/tidying up!

[bediu]

Is there a way to add multiple response types from one request?

[bediu]

@jozsefsallai