Describing the REST Endpoint structure and usage through the frontend

The Openroberta lab consists of the browser-based UI layer, a large collection of Javascript files, a backend, based on an embedded Jetty server and a database server. The Jetty server is based on the REST paradigm, the REST services are called from the frontend. The payload is based on JSON objects.

It would be of great help to have a

• short description of the REST architecture (linking to the many resources in the web)
• a documentation of our REST services and how they are used by the frontend
• examples of the usage, that can be executed by tools as curl, for instance

It is a big problem, that this kind of documentation becomes outdated very soon. So ist would be of great help, if the documentation could be generated from our sources by suitable frameworks as swagger. Whether such a framework is selected and which is selected should be based on an easy integration into our git - maven - docker based architecture.