[Hawkular-dev] [Metrics] Better REST API documentation, feedback needed

Hi, Currently our REST API documentation is generated solely from Swagger annotations. This is a good starting point, but I believe it's not enough nor easy for new users. I filed this JIRA: HWKMETRICS-297 Incorporate static blocks into the REST API documentation https://issues.jboss.org/browse/HWKMETRICS-297 And started the PR: https://github.com/hawkular/hawkular-metrics/pull/389 Here's what I have in mind: - provide general information which does not fit in annotations into a base Asciidoc file - merge the static file with the Swagger generated one Many services organize their REST API documentation similarly (I liked GitHub and PagerDuty examples in particular). I need your opinion on the static file plan. I started with this: https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMET... Can you think of anything missing? Or do you have any comments? Of course the result doc is not perfect, but it's a step forward. Thanks, Thomas