Agreed on general information !

I would like us to break some barriers between components.

There are likely notions that should to be shared and shouldn't be just copied over and over. (Obvious ones are Tenant and Timestamps)

So I would like to see the APIs in a single page (like Pager Duty) with general information followed by Metrics, Alerts,... sections.

On Tue, Oct 6, 2015 at 3:45 PM, Thomas Segismont <tsegismo@redhat.com> wrote:

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

_______________________________________________
hawkular-dev mailing list
hawkular-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev