Insomnia: [Feature] Generate documentation

[nkostadinov]

Since there is a place to write documentation for each request I think it would be really nice if the app can generate documentation with examples.

And 10x for the great application ! 👍

[gschier]

Thanks for the request @nkostadinov! This is definitely something I'd like to add in the longer-term. Perhaps you could expand your description with more details on what exactly you are looking for? Any example tools, screenshots, or general notes would help a lot.

[mbedded]

This sounds interesting but i have some questions/remarks here:

1. Who is the author of the WebAPI? Normally the authors are giving an example and documentation of their interface. So i guess this place is more accurate than within Insomnia.
2. Maybe there could be another column on the right or below (within the request data) which contains a textfield for writing documentation. I assume some kind of export (maybe html) would be needed.

[nkostadinov]

The way I see it , the app can generate html file(s) with something with the following structure:

[NAME]
[METHOD] /url/to/endpoint
[CONTENT TYPE] e.g. JSON, XML, BINARY 
[AUTH]

[Docs] - what you write in the docs section of the app

Sample request:
[REQUEST]
Sample response:
[RESPONSE]

(optionally include the timeline)

All the items in [] are taken directly from the app. I test almost every possible REST action via the app so in the end this could generate really meaningful documentation.

@mbedded there is already a Docs section in the app, thats where I got the idea from

[mbedded]

Thank you for your information @nkostadinov :) I saw the "Docs"-Tab but i was confused by the popup. So i thought there is no appropriate place to document requests somehow. From my point of view your output example is good. I guess the parameters (if there are some) will be listed in [REQUEST], right?

Maybe there could be a template-file for the generated output so i could specify the order of fields or (maybe) customize the output with HTML or CSS.
_Hint: I don't want to bloat this issue more than necessary. I guess we should start with a default output and keep customizing in mind. Maybe the default is enough or there should be a new issue for templating._

With a good output the files could be used to expose the API for users/devs.

[msassak]

Automatically generating docs is a great feature. The lack of them in Insomnia is one of the reasons we (reluctantly) decided to use Postman Pro at work. This is too bad, because Insomnia is much nicer than Postman in almost every single respect.

[mc-funk]

It would be spectacular, now that Docs are markdown enabled, to be able to export Markdown with the simple format

*Request: *

<Request>

*Response: *

<Response>

[garnold]

👍

[alexmassicott]

yes please

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[eduwass]

I found this: https://github.com/mlabouardy/swaggymnia

Maybe useful for anyone that needs this functionality.

[willianhf]

Automatically generating docs is a great feature. The lack of them in Insomnia is one of the reasons we (reluctantly) decided to use Postman Pro at work. This is too bad, because Insomnia is much nicer than Postman in almost every single respect.

Here too, using Postman because of autogenerated docs.
So, that feature was abandoned?

[gschier]

We may attempt to do something like this in the future but, for now, it's not on the roadmap.

There is another awesome community project created by @jozsefsallai that's worth looking at https://github.com/jozsefsallai/insomnia-documenter

[willianhf]

@gschier thanks for recommend, sure I'll use it!

[BradRyan]

It would be cool it if there was a way (maybe there is?) to make a template for the documentation within Insomnia itself. Similar to how you can have a default template for new pull requests in GitHub. Every time I make a new endpoint I am recreating (or copy/pasting) the same format from other requests. Also, new team member often skip the documentation or don't fill it out with the same format, and this helps explain what is expected.

A simple example would be something like:

docs_template.md
````
Add short description of endpoint here...

REQUEST

POST /api/thing/:thing_id

RESPONSE

Paste example respond here

````