[aerogear-dev] License Key for AeroGear UnifiedPush Server (was: Re: do we want swagger for REST endpoint documentation?)
Matthias Wessendorf
matzew at apache.org
Thu Apr 9 03:46:39 EDT 2015
Hi Miredot team,
for the AeroGear UnifiedPush Server ([1], [2]), we would like to start
using miredot for our jaxrs endpoints ([3]). The Maven groupId is
"org.jboss.aerogear.unifiedpush" and the artifactId is "unifiedpush-jaxrs".
Currently we are using jaxrs-doclet ([4]), but we are not happy with that.
The Server is an OpenSource project with regular releases, and it is
licensed under the Apache 2.0 license.
For this project we would like to request an opensource license.
Thanks,
Matthias
[1] https://aerogear.org/push/#unifiedpush
[2] https://aerogear.org/docs/unifiedpush/ups_userguide/index/
[3]
https://github.com/aerogear/aerogear-unifiedpush-server/tree/master/jaxrs
[4]
https://aerogear.org/docs/specs/aerogear-unifiedpush-rest/overview-index.html
On Tue, Apr 7, 2015 at 1:57 PM, Idel Pivnitskiy <idel.pivnitskiy at gmail.com>
wrote:
> 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>
>
> _______________________________________________
> 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/20150409/fc388540/attachment-0001.html
More information about the aerogear-dev
mailing list