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

Swagger allows doc on the source as well, right ? Just wondering. REgarding license, I need to double check on that before... On Tue, Apr 7, 2015 at 11:57 AM, Idel Pivnitskiy < idel.pivnitskiy(a)gmail.com&gt; wrote: > Matthias, > > Sure, I will work on it. > But I think that it would be better if you request a license [1] on your > email and forward it to me. > It won't be a problem to use a free version, but pro version has a very > cool features, like: > > - Display javadoc comments for the fields of json payloads and enums > - JSON field documentation > - Type replacement (custom serialisation, JSON types) > > Please, request a li > > [1] http://miredot.com/price/ > > 2015-04-07 12:44 GMT+03:00 Matthias Wessendorf <matzew(a)apache.org&gt;: > >> Idel, >> >> would you mind to create a branch for us, so we can investigate the >> MireDot solution? also the build should be working w/ JDK8. >> >> ATM we use jax-doclet ([1]) which does not work w/ JDK 8 - but it does >> not really use any fancy annotations (e.g. see [2]) - that's why we picked >> it. >> >> Thanks! >> Matthias >> >> [1] http://fromage.github.io/jax-doclets/docs/0.10.0/html/ >> [2] >> https://github.com/aerogear/aerogear-unifiedpush-server/blob/master/jaxrs... >> >> On Tue, Apr 7, 2015 at 9:54 AM, Lukáš Fryč <lukas.fryc(a)gmail.com&gt; 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(a)gmail.com&gt; 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(a)apache.org&gt;: >>>> >>>>> >>>>> >>>>> On Fri, Apr 3, 2015 at 10:27 PM, Heiko W.Rupp <hrupp(a)redhat.com&gt; >>>>> 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(a)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(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>>> >>>> >>>> >>>> >>>> -- >>>> Best regards, >>>> Idel Pivnitskiy >>>> E-mail: Idel.Pivnitskiy(a)gmail.com >>>> Twitter: @idelpivnitskiy <https://twitter.com/idelpivnitskiy> >>>> GitHub: @idelpivnitskiy <https://github.com/idelpivnitskiy> >>>> _______________________________________________ >>>> aerogear-dev mailing list >>>> aerogear-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>> >>> >>> _______________________________________________ >>> aerogear-dev mailing list >>> aerogear-dev(a)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(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/aerogear-dev >> > > > > -- > Best regards, > Idel Pivnitskiy > E-mail: Idel.Pivnitskiy(a)gmail.com > Twitter: @idelpivnitskiy <https://twitter.com/idelpivnitskiy> > GitHub: @idelpivnitskiy <https://github.com/idelpivnitskiy> > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)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(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev