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

On Tue, Apr 7, 2015 at 12:56 PM, Idel Pivnitskiy < idel.pivnitskiy(a)gmail.com&gt; wrote: > Yes, Swagger can generate doc on the fly, but Swagger use its own > annotations instead of parse JAX-RS annotations and javadoc, like MireDot. > Ok, I think I have not a huge concern against custom annotations, especially due to the wide adoption of Swagger. I guess it's just a very tiny JAR, that contains the annotations, right? (+ the build time tool dependency for processing) > What about licence: Apache Tika, for example, uses pro version of MireDot > > > https://github.com/apache/tika/blob/5fbc56cca94b9da0a914e82dd466abb139f9e... > Thanks for the example, that's helpful > > > 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 > -- 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