[Hawkular-dev] [Metrics] Better REST API documentation, feedback needed
Gary Brown
gbrown at redhat.com
Wed Oct 7 08:56:07 EDT 2015
Content looks good. Is there going to be an index to help navigation of the document?
Regards
Gary
----- Original Message -----
> I've updated the base documentation:
>
> https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMETRICS-297/api/metrics-api-jaxrs/src/main/rest-doc/base.adoc
>
> Attached is a sample of the merge result (base documentation + swagger).
>
> If you've ever felt short of information when using the Metrics REST
> API, this is an opportunity to chime in for improvements.
>
> Le 07/10/2015 10:48, Thomas Heute a écrit :
> > 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
> > <mailto: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 <mailto:hawkular-dev at lists.jboss.org>
> > https://lists.jboss.org/mailman/listinfo/hawkular-dev
> >
> >
> >
> >
> >
> > _______________________________________________
> > hawkular-dev mailing list
> > hawkular-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/hawkular-dev
> >
>
>
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>
More information about the hawkular-dev
mailing list