Well,

we are on the crossroad guys :) Even such simple task as generating
API automatically can be done by different means.

I do not mind either approach. If Idel is about to do it, feel free to
do so. I do not know Miredot and I would personally stick to something
proven and widely used, even it does not cover our need 100% and it is
not all shiny and cool.

I would personaly do simple Swagger YAML and I would not integrate it
to sources directly. Having it separate has another advantage like you
can move that YAML here and there plus you can design endpoints and
you can share it with other people before you even start to implement
it.

>From my point of view in work, this is really marginal issue for me
right now. I just proposed the idea.

Regards

On Tue, Apr 7, 2015 at 9:54 AM, Lukáš Fryč <lukas.fryc@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@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@apache.org>:
>>>
>>>
>>>
>>> On Fri, Apr 3, 2015 at 10:27 PM, Heiko W.Rupp <hrupp@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@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@lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>>
>>
>> --
>> Best regards,
>> Idel Pivnitskiy
>> E-mail: Idel.Pivnitskiy@gmail.com
>> Twitter: @idelpivnitskiy
>> GitHub: @idelpivnitskiy
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev@lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev@lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev



--

Stefan Miklosovic
Red Hat Brno - JBoss Mobile Platform

e-mail: smikloso@redhat.com
irc: smikloso

_______________________________________________
aerogear-dev mailing list
aerogear-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev