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

[Matthias Wessendorf]

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