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

[Thomas Heute]

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 at 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 at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/hawkular-dev/attachments/20151007/8870a132/attachment.html