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

[Thomas Segismont]

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/HWKMETRICS-297/api/metrics-api-jaxrs/src/main/rest-doc/base.adoc

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