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_Ne... Heiko *) Those are runtime annotations and do not require the servlet being deployed or anything.