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

Yes, Swagger can generate doc on the fly, but Swagger use its own annotations instead of parse JAX-RS annotations and javadoc, like MireDot.

What about licence: Apache Tika, for example, uses pro version of MireDot https://github.com/apache/tika/blob/5fbc56cca94b9da0a914e82dd466abb139f9e...

2015-04-07 13:48 GMT+03:00 Matthias Wessendorf <matzew(a)apache.org&gt;: > 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 > _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev