[aerogear-dev] do we want swagger for REST endpoint documentation?
Matthias Wessendorf
matzew at apache.org
Tue Apr 7 08:16:30 EDT 2015
sounds like a good plan
On Tue, Apr 7, 2015 at 1:59 PM, Idel Pivnitskiy <idel.pivnitskiy at gmail.com>
wrote:
> 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 at gmail.com>:
>
>> Ok, so I will wait a license key from you.
>>
>> 2015-04-07 14:55 GMT+03:00 Matthias Wessendorf <matzew at apache.org>:
>>
>>>
>>>
>>> On Tue, Apr 7, 2015 at 1:42 PM, Idel Pivnitskiy <
>>> idel.pivnitskiy at 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 at apache.org>:
>>>>
>>>>>
>>>>>
>>>>> On Tue, Apr 7, 2015 at 12:56 PM, Idel Pivnitskiy <
>>>>> idel.pivnitskiy at 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
>>>>>> MireDot
>>>>>>
>>>>>>
>>>>>> https://github.com/apache/tika/blob/5fbc56cca94b9da0a914e82dd466abb139f9e3f4/tika-server/pom.xml#L248-L266
>>>>>>
>>>>>
>>>>> Thanks for the example, that's helpful
>>>>>
>>>>>
>>>>>>
>>>>>>
>>>>>> 2015-04-07 13:48 GMT+03:00 Matthias Wessendorf <matzew at 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 at 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 li
>>>>>>>>
>>>>>>>> [1] http://miredot.com/price/
>>>>>>>>
>>>>>>>> 2015-04-07 12:44 GMT+03:00 Matthias Wessendorf <matzew at 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!
>>>>>>>>> Matthias
>>>>>>>>>
>>>>>>>>> [1] http://fromage.github.io/jax-doclets/docs/0.10.0/html/
>>>>>>>>> [2]
>>>>>>>>> https://github.com/aerogear/aerogear-unifiedpush-server/blob/master/jaxrs/src/main/java/org/jboss/aerogear/unifiedpush/rest/sender/PushNotificationSenderEndpoint.java#L99-L102
>>>>>>>>>
>>>>>>>>> On Tue, Apr 7, 2015 at 9:54 AM, Lukáš Fryč <lukas.fryc at 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 at gmail.com> 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 at apache.org
>>>>>>>>>>> >:
>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>> On Fri, Apr 3, 2015 at 10:27 PM, Heiko W.Rupp <hrupp at 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 at 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 at lists.jboss.org
>>>>>>>>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> --
>>>>>>>>>>> Best regards,
>>>>>>>>>>> Idel Pivnitskiy
>>>>>>>>>>> E-mail: Idel.Pivnitskiy at gmail.com
>>>>>>>>>>> Twitter: @idelpivnitskiy <https://twitter.com/idelpivnitskiy>
>>>>>>>>>>> GitHub: @idelpivnitskiy <https://github.com/idelpivnitskiy>
>>>>>>>>>>> _______________________________________________
>>>>>>>>>>> aerogear-dev mailing list
>>>>>>>>>>> aerogear-dev at lists.jboss.org
>>>>>>>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> _______________________________________________
>>>>>>>>>> aerogear-dev mailing list
>>>>>>>>>> aerogear-dev at 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 at lists.jboss.org
>>>>>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>> Best regards,
>>>>>>>> Idel Pivnitskiy
>>>>>>>> E-mail: Idel.Pivnitskiy at gmail.com
>>>>>>>> Twitter: @idelpivnitskiy <https://twitter.com/idelpivnitskiy>
>>>>>>>> GitHub: @idelpivnitskiy <https://github.com/idelpivnitskiy>
>>>>>>>>
>>>>>>>> _______________________________________________
>>>>>>>> aerogear-dev mailing list
>>>>>>>> aerogear-dev at 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 at lists.jboss.org
>>>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> _______________________________________________
>>>>>> aerogear-dev mailing list
>>>>>> aerogear-dev at 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 at lists.jboss.org
>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>>>>
>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> aerogear-dev mailing list
>>>> aerogear-dev at 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 at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>>
>>
>>
>>
>> --
>> Best regards,
>> Idel Pivnitskiy
>> E-mail: Idel.Pivnitskiy at gmail.com
>> Twitter: @idelpivnitskiy <https://twitter.com/idelpivnitskiy>
>> GitHub: @idelpivnitskiy <https://github.com/idelpivnitskiy>
>>
>
>
>
> --
> Best regards,
> Idel Pivnitskiy
> E-mail: Idel.Pivnitskiy at gmail.com
> Twitter: @idelpivnitskiy <https://twitter.com/idelpivnitskiy>
> GitHub: @idelpivnitskiy <https://github.com/idelpivnitskiy>
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20150407/465fd358/attachment-0001.html
More information about the aerogear-dev
mailing list