[aerogear-dev] do we want swagger for REST endpoint documentation?
Idel Pivnitskiy
idel.pivnitskiy at gmail.com
Tue Apr 7 07:59:40 EDT 2015
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>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20150407/a6ae39dd/attachment-0001.html
More information about the aerogear-dev
mailing list