On Tue, Apr 7, 2015 at 1:42 PM, Idel Pivnitskiy <idel.pivnitskiy@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!-Matthias2015-04-07 14:11 GMT+03:00 Matthias Wessendorf <matzew@apache.org>:On Tue, Apr 7, 2015 at 12:56 PM, Idel Pivnitskiy <idel.pivnitskiy@gmail.com> 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 MireDotThanks for the example, that's helpful2015-04-07 13:48 GMT+03:00 Matthias Wessendorf <matzew@apache.org>: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@gmail.com> 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 li2015-04-07 12:44 GMT+03:00 Matthias Wessendorf <matzew@apache.org>: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!MatthiasOn Tue, Apr 7, 2015 at 9:54 AM, Lukáš Fryč <lukas.fryc@gmail.com> 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@gmail.com> napsal:For JAX-RS I prefer use MireDot as a REST API doc generatorWith 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@apache.org>:On Fri, Apr 3, 2015 at 10:27 PM, Heiko W.Rupp <hrupp@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.+1000we are, atm, doing similar:sourceresult: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@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@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev--_______________________________________________Best regards,Idel PivnitskiyE-mail: Idel.Pivnitskiy@gmail.comTwitter: @idelpivnitskiyGitHub: @idelpivnitskiy
aerogear-dev mailing list
aerogear-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev
_______________________________________________
aerogear-dev mailing list
aerogear-dev@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@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev--Best regards,Idel PivnitskiyE-mail: Idel.Pivnitskiy@gmail.comTwitter: @idelpivnitskiyGitHub: @idelpivnitskiy
_______________________________________________
aerogear-dev mailing list
aerogear-dev@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@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev
_______________________________________________
aerogear-dev mailing list
aerogear-dev@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@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev
_______________________________________________
aerogear-dev mailing list
aerogear-dev@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@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev