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

Tue Apr 7 06:56:51 EDT 2015

Yes, Swagger can generate doc on the fly, but Swagger use its own
annotations instead of parse JAX-RS annotations and javadoc, like MireDot.
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

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20150407/8d4c1253/attachment-0001.html 