<div dir="ltr"><div>Agreed on general information !</div><div><br></div>I would like us to break some barriers between components.<div>There are likely notions that should to be shared and shouldn't be just copied over and over. (Obvious ones are Tenant and Timestamps)</div><div><br></div><div>So I would like to see the APIs in a single page (like Pager Duty) with general information followed by Metrics, Alerts,... sections.</div><div><br></div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Oct 6, 2015 at 3:45 PM, Thomas Segismont <span dir="ltr"><<a href="mailto:tsegismo@redhat.com" target="_blank">tsegismo@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi,<br>
<br>
Currently our REST API documentation is generated solely from Swagger<br>
annotations.<br>
<br>
This is a good starting point, but I believe it's not enough nor easy<br>
for new users.<br>
<br>
I filed this JIRA:<br>
<br>
HWKMETRICS-297 Incorporate static blocks into the REST API documentation<br>
<a href="https://issues.jboss.org/browse/HWKMETRICS-297" rel="noreferrer" target="_blank">https://issues.jboss.org/browse/HWKMETRICS-297</a><br>
<br>
And started the PR:<br>
<a href="https://github.com/hawkular/hawkular-metrics/pull/389" rel="noreferrer" target="_blank">https://github.com/hawkular/hawkular-metrics/pull/389</a><br>
<br>
Here's what I have in mind:<br>
- provide general information which does not fit in annotations into a<br>
base Asciidoc file<br>
- merge the static file with the Swagger generated one<br>
<br>
Many services organize their REST API documentation similarly (I liked<br>
GitHub and PagerDuty examples in particular).<br>
<br>
I need your opinion on the static file plan. I started with this:<br>
<a href="https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMETRICS-297/api/metrics-api-jaxrs/src/main/rest-doc/base.adoc" rel="noreferrer" target="_blank">https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMETRICS-297/api/metrics-api-jaxrs/src/main/rest-doc/base.adoc</a><br>
<br>
Can you think of anything missing? Or do you have any comments?<br>
<br>
Of course the result doc is not perfect, but it's a step forward.<br>
<br>
Thanks,<br>
Thomas<br>
<br>
_______________________________________________<br>
hawkular-dev mailing list<br>
<a href="mailto:hawkular-dev@lists.jboss.org">hawkular-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/hawkular-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/hawkular-dev</a><br>
<br>
<br>
</blockquote></div><br></div>