I wonder if we should not consider creation of something like http://petstore.swagger.io/ which would be good as this would be interactive help with UI deployed on every installation.

%kobit what do you think about this instead of creation of examples on project Wiki page?

I agree, that would be definitely a better option. I wonder, however, how much longer it would take than writing a wiki?

On the other hand, I understand, that such a framework would take care of any new command we add automatically....

In any case, I am approving the idea.

It took me a while but I prepared mechanism for documentation of REST API in which we describe usage of REST API call inside REST API scripts responsible for handling each request.

This is later used by Tigase HTTP API component REST module to present list of available REST API calls at /rest/ url - by default it will be available at http://localhost:8080/rest/. After clicking on each call you will get details of this request and examples of how to use it. This way each installation will present valid documetation for each REST API call available on this installation and if new call will be added then documentation will be added to this new page.

I checked this on our test cluster and it looks super cool. Good work. Could you please provide more details on how to prepare a script with such documentation?

More specifically, what I would like to know is this:

Let's say we have this admin UI at address: http://localhost:8080/admin/ and we have a bunch of admin commands available. I noticed that not all of the admin commands have the corresponding documentation at the http://localhost:8080/rest/ link. What do we need to do to have all of the commands documented? And another question. It would be great to have on the /admin/ page at each admin command a small link which would show the documentation for the API call for this command. It can be a direct link to the /rest/ page with expanded this one command.