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

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