I really like the idea! On Fri, Apr 3, 2015 at 11:06 AM, Stefan Miklosovic <smikloso(a)redhat.com <javascript:_e(%7B%7D,'cvml','smikloso@redhat.com');>> wrote: > Hello, > > Is there any interest to describe REST API for UPS in a Swagger? (1),(2) > > I can imagine it would be pretty handy for folks, it is just one yaml > file to write really. > > It could be somehow linked in UPS web page, swagger is just pure html > + js without any dependencies at all. > > (1) http://swagger.io/ > (2) http://petstore.swagger.io/#!/pet/deletePet > > -- > Stefan Miklosovic > Red Hat Brno - JBoss Mobile Platform > > e-mail: smikloso(a)redhat.com > <javascript:_e(%7B%7D,'cvml','smikloso@redhat.com');> > irc: smikloso > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > <javascript:_e(%7B%7D,'cvml','aerogear-dev@lists.jboss.org');> > https://lists.jboss.org/mailman/listinfo/aerogear-dev >

+1 feels free to PR this On Fri, Apr 3, 2015 at 1:10 PM, Matthias Wessendorf <matzew(a)apache.org&gt; wrote: > that is very cool! > > Also this helps to retire the jaxrs doclet, that is not working w/ jdk8 > > > On Friday, April 3, 2015, Karel Piwko <kpiwko(a)redhat.com&gt; wrote: > >> I really like the idea! >> >> On Fri, Apr 3, 2015 at 11:06 AM, Stefan Miklosovic <smikloso(a)redhat.com&gt; >> wrote: >> >>> Hello, >>> >>> Is there any interest to describe REST API for UPS in a Swagger? (1),(2) >>> >>> I can imagine it would be pretty handy for folks, it is just one yaml >>> file to write really. >>> >>> It could be somehow linked in UPS web page, swagger is just pure html >>> + js without any dependencies at all. >>> >>> (1) http://swagger.io/ >>> (2) http://petstore.swagger.io/#!/pet/deletePet >>> >>> -- >>> Stefan Miklosovic >>> Red Hat Brno - JBoss Mobile Platform >>> >>> e-mail: smikloso(a)redhat.com >>> irc: smikloso >>> _______________________________________________ >>> aerogear-dev mailing list >>> aerogear-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>> >> >> > > -- > Sent from Gmail Mobile > > _______________________________________________ > 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

On Apr 3, 2015, at 5:06 AM, Stefan Miklosovic <smikloso(a)redhat.com&gt; wrote: Hello, Is there any interest to describe REST API for UPS in a Swagger? (1),(2)

I can imagine it would be pretty handy for folks, it is just one yaml file to write really. It could be somehow linked in UPS web page, swagger is just pure html + js without any dependencies at all. (1) http://swagger.io/ (2) http://petstore.swagger.io/#!/pet/deletePet -- Stefan Miklosovic Red Hat Brno - JBoss Mobile Platform e-mail: smikloso(a)redhat.com irc: smikloso _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

we are using it in Project Newcastle with annotations on the endpoints, and it's really handy.

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.

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

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

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(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... >>> result: >>> >>> https://aerogear.org/docs/specs/aerogear-unifiedpush-rest/sender/index.ht... >>> >>> 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 >> GitHub: @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 -- Stefan Miklosovic Red Hat Brno - JBoss Mobile Platform e-mail: smikloso(a)redhat.com irc: smikloso _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

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

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

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

On Tue, Apr 7, 2015 at 1:42 PM, Idel Pivnitskiy <idel.pivnitskiy(a)gmail.com > wrote: > IMO, custom annotations force you to duplicate code and documentation. > Take a look at a more detailed example: > > @POST > @Path("/{petId}") > @Consumes({MediaType.APPLICATION_FORM_URLENCODED}) > @ApiOperation(value = "Updates a pet in the store with form data", > consumes = MediaType.APPLICATION_FORM_URLENCODED) > @ApiResponses(value = { > @ApiResponse(code = 405, message = "Invalid input")}) > public Response updatePetWithForm ( > @ApiParam(value = "ID of pet that needs to be updated", required = true)@PathParam("petId") String petId, > @ApiParam(value = "Updated name of the pet", required = false)@FormParam("name") String name, > @ApiParam(value = "Updated status of the pet", required = false)@FormParam("status") String status) { > System.out.println(name); > System.out.println(status); > return Response.ok().entity(new com.wordnik.swagger.sample.model.ApiResponse(200, "SUCCESS")).build(); > } > > > It is much more simple with MireDot (also because javadoc could be > generated automatically by IDE): > > /** > * Updates a pet in the store with form data. > * > * @param petId ID of pet that needs to be updated > * @param name Updated name of the pet > * @param status Updated status of the pet > */ > @POST > @Path("/{petId}") > @Consumes({MediaType.APPLICATION_FORM_URLENCODED}) > public Response updatePetWithForm (@PathParam("petId") String petId, > @FormParam("name") String name, > @FormParam("status") String status) { > System.out.println(name); > System.out.println(status); > return Response.ok().entity(new com.wordnik.swagger.sample.model.ApiResponse(200, "SUCCESS")).build(); > } > > Really, I don't know why Swagger is so popular :) > That's quite a difference, and less verbose and less of duplication (DRY). So I'd say, let's try Miredot :-) Thanks for the valuable info, Idel! -Matthias > > 2015-04-07 14:11 GMT+03:00 Matthias Wessendorf <matzew(a)apache.org&gt;: > >> >> >> 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 >> > > > > _______________________________________________ > 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

We may try to start with free version (because it will be faster) and request a pro version later. 2015-04-07 14:57 GMT+03:00 Idel Pivnitskiy <idel.pivnitskiy(a)gmail.com&gt;: > Ok, so I will wait a license key from you. > > 2015-04-07 14:55 GMT+03:00 Matthias Wessendorf <matzew(a)apache.org&gt;: > >> >> >> On Tue, Apr 7, 2015 at 1:42 PM, Idel Pivnitskiy < >> idel.pivnitskiy(a)gmail.com&gt; wrote: >> >>> IMO, custom annotations force you to duplicate code and documentation. >>> Take a look at a more detailed example: >>> >>> @POST >>> @Path("/{petId}") >>> @Consumes({MediaType.APPLICATION_FORM_URLENCODED}) >>> @ApiOperation(value = "Updates a pet in the store with form data", >>> consumes = MediaType.APPLICATION_FORM_URLENCODED) >>> @ApiResponses(value = { >>> @ApiResponse(code = 405, message = "Invalid input")}) >>> public Response updatePetWithForm ( >>> @ApiParam(value = "ID of pet that needs to be updated", required = true)@PathParam("petId") String petId, >>> @ApiParam(value = "Updated name of the pet", required = false)@FormParam("name") String name, >>> @ApiParam(value = "Updated status of the pet", required = false)@FormParam("status") String status) { >>> System.out.println(name); >>> System.out.println(status); >>> return Response.ok().entity(new com.wordnik.swagger.sample.model.ApiResponse(200, "SUCCESS")).build(); >>> } >>> >>> >>> It is much more simple with MireDot (also because javadoc could be >>> generated automatically by IDE): >>> >>> /** >>> * Updates a pet in the store with form data. >>> * >>> * @param petId ID of pet that needs to be updated >>> * @param name Updated name of the pet >>> * @param status Updated status of the pet >>> */ >>> @POST >>> @Path("/{petId}") >>> @Consumes({MediaType.APPLICATION_FORM_URLENCODED}) >>> public Response updatePetWithForm (@PathParam("petId") String petId, >>> @FormParam("name") String name, >>> @FormParam("status") String status) { >>> System.out.println(name); >>> System.out.println(status); >>> return Response.ok().entity(new com.wordnik.swagger.sample.model.ApiResponse(200, "SUCCESS")).build(); >>> } >>> >>> Really, I don't know why Swagger is so popular :) >>> >> >> That's quite a difference, and less verbose and less of duplication >> (DRY). So I'd say, let's try Miredot :-) >> >> Thanks for the valuable info, Idel! >> >> -Matthias >> >> >>> >>> 2015-04-07 14:11 GMT+03:00 Matthias Wessendorf <matzew(a)apache.org&gt;: >>> >>>> >>>> >>>> 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 >>>>>>>>>> >: >>>>>>>>>> >>>>>>>>>>> >>>>>>>>>>> >>>>>>>>>>> On Fri, Apr 3, 2015 at 10:27 PM, Heiko W.Rupp <hrupp(a)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(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 >>>> >>> >>> >>> >>> _______________________________________________ >>> 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> > -- 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