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

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