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

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&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 > -- Best regards, Idel Pivnitskiy E-mail: Idel.Pivnitskiy(a)gmail.com Twitter: @idelpivnitskiy <https://twitter.com/idelpivnitskiy> GitHub: @idelpivnitskiy <https://github.com/idelpivnitskiy>