[aerogear-dev] do we want swagger for REST endpoint documentation?

Tue Apr 7 04:29:41 EDT 2015

having it separate did not work out. We had that in the past.
Even today, where the source code comments is used, not every API changes
is automatically catched (lack of updates on the documentation/comments).

However, since both live together (comments/doc and source), it is IMO less
of a hassle to get things updated.

On Tue, Apr 7, 2015 at 10:10 AM, Stefan Miklosovic <smikloso at redhat.com>
wrote:

> Well,
>
> we are on the crossroad guys :) Even such simple task as generating
> API automatically can be done by different means.
>
> I do not mind either approach. If Idel is about to do it, feel free to
> do so. I do not know Miredot and I would personally stick to something
> proven and widely used, even it does not cover our need 100% and it is
> not all shiny and cool.
>
> I would personaly do simple Swagger YAML and I would not integrate it
> to sources directly. Having it separate has another advantage like you
> can move that YAML here and there plus you can design endpoints and
> you can share it with other people before you even start to implement
> it.
>
> From my point of view in work, this is really marginal issue for me
> right now. I just proposed the idea.
>
> Regards
>
> On Tue, Apr 7, 2015 at 9:54 AM, Lukáš Fryč <lukas.fryc at gmail.com> wrote:
> > I agree with Idel that DRY approach in Miredot's case seems more
> appealing.
> >
> > They offer basic docs generation in Free version, but also Pro version
> for
> > open-source projects under conditions that Aerogear meets [1].
> >
> > ~ Lukas
> >
> > [1] http://www.miredot.com/price/
> >
> > ne 5. 4. 2015 v 20:00 odesílatel Idel Pivnitskiy <
> idel.pivnitskiy at gmail.com>
> > napsal:
> >
> >> For JAX-RS I prefer use MireDot as a REST API doc generator
> >> http://www.miredot.com/
> >>
> >> With MireDot you do not need to use additional annotations, like @Api:
> >>
> >> @Path("/pet")
> >> @Api(value = "/pet", description = "Operations about pets")
> >>
> >>
> >> It will parse your JAX-RS annotation and pure javadoc:
> >>
> >> /**
> >> * Operations about pets
> >> */
> >> @Path("/pet")
> >>
> >> and generate beautiful and user friendly documentation, like this:
> >> http://www.miredot.com/exampledocs/
> >> Swagger example: http://petstore.swagger.io/
> >>
> >> And MireDot is free for open source projects!
> >>
> >> Think about this alternative for Swagger. I'm able to prepare Pull
> Request
> >> for UPS next week.
> >>
> >>
> >> 2015-04-04 9:43 GMT+03:00 Matthias Wessendorf <matzew at apache.org>:
> >>>
> >>>
> >>>
> >>> On Fri, Apr 3, 2015 at 10:27 PM, Heiko W.Rupp <hrupp at redhat.com>
> wrote:
> >>>>
> >>>> On 3 Apr 2015, at 18:53, Andrea Vibelli wrote:
> >>>>
> >>>> > we are using it in Project Newcastle with annotations on the
> >>>> > endpoints, and
> >>>> > it's really handy.
> >>>>
> >>>> All the JBoss ON 3.2+ and RHQ REST-docs are generated from JAX-RS +
> >>>> Swagger annotations.
> >>>> In Hawkular we are basically doing the same, but with a different
> >>>> annotation processor.
> >>>
> >>>
> >>> +1000
> >>>
> >>> we are, atm, doing similar:
> >>> source
> >>>
> >>>
> https://github.com/aerogear/aerogear-unifiedpush-server/blob/master/jaxrs/src/main/java/org/jboss/aerogear/unifiedpush/rest/sender/PushNotificationSenderEndpoint.java#L99-L102
> >>> result:
> >>>
> >>>
> https://aerogear.org/docs/specs/aerogear-unifiedpush-rest/sender/index.html#POST
> >>>
> >>> but the jaxrs doclet does not work w/ JDK8 - something has to change
> here
> >>> ;-)
> >>> So, I am all for using Swagger annotations on the code to generate the
> >>> HTML docs :-)
> >>>
> >>> Greetings,
> >>> Matthias
> >>>
> >>>>
> >>>>
> >>>> I personally think the best is really to have the annotations in the
> >>>> source and not trying
> >>>> to update a separate .yml file, as the latter usually is much easier
> >>>> forgotten.
> >>>> _______________________________________________
> >>>> aerogear-dev mailing list
> >>>> aerogear-dev at lists.jboss.org
> >>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
> >>>
> >>>
> >>>
> >>>
> >>> --
> >>> Matthias Wessendorf
> >>>
> >>> blog: http://matthiaswessendorf.wordpress.com/
> >>> sessions: http://www.slideshare.net/mwessendorf
> >>> twitter: http://twitter.com/mwessendorf
> >>>
> >>> _______________________________________________
> >>> aerogear-dev mailing list
> >>> aerogear-dev at lists.jboss.org
> >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
> >>
> >>
> >>
> >>
> >> --
> >> Best regards,
> >> Idel Pivnitskiy
> >> E-mail: Idel.Pivnitskiy at gmail.com
> >> Twitter: @idelpivnitskiy
> >> GitHub: @idelpivnitskiy
> >> _______________________________________________
> >> aerogear-dev mailing list
> >> aerogear-dev at lists.jboss.org
> >> https://lists.jboss.org/mailman/listinfo/aerogear-dev
> >
> >
> > _______________________________________________
> > aerogear-dev mailing list
> > aerogear-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/aerogear-dev
>
>
>
> --
> Stefan Miklosovic
> Red Hat Brno - JBoss Mobile Platform
>
> e-mail: smikloso at redhat.com
> irc: smikloso
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>

-- 
Matthias Wessendorf

blog: http://matthiaswessendorf.wordpress.com/
sessions: http://www.slideshare.net/mwessendorf
twitter: http://twitter.com/mwessendorf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20150407/32810d05/attachment-0001.html 