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

Tue Apr 7 06:48:29 EDT 2015

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