[Hawkular-dev] REST-api docs

[Heiko W.Rupp]

Hey,

We should add the swagger annotations(*) to the rest-api to have
the documentation source where the rest-annotations live and not
in separate readme files, that get outdated pretty quickly.

The annotations are then processed by an annotation processor
and can be (via the one we have) be turned into xml , html, docbook.
In fact I can hack the processor to also emit AsciiDoc which then can
be easily added to the developer documentation.

RHQ has some pretty extensive usage of the swagger annotations - 
the result in the JON documentation can be browsed here

https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Operations_Network/3.3/html/Rest_API/index.html

  Heiko


*) Those are runtime annotations and do not require the servlet being
deployed or anything.