<div dir="ltr">having it separate did not work out. We had that in the past.<div>Even today, where the source code comments is used, not every API changes is automatically catched (lack of updates on the documentation/comments).</div><div><br></div><div>However, since both live together (comments/doc and source), it is IMO less of a hassle to get things updated. </div><div><br></div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Apr 7, 2015 at 10:10 AM, Stefan Miklosovic <span dir="ltr"><<a href="mailto:smikloso@redhat.com" target="_blank">smikloso@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Well,<br>
<br>
we are on the crossroad guys :) Even such simple task as generating<br>
API automatically can be done by different means.<br>
<br>
I do not mind either approach. If Idel is about to do it, feel free to<br>
do so. I do not know Miredot and I would personally stick to something<br>
proven and widely used, even it does not cover our need 100% and it is<br>
not all shiny and cool.<br>
<br>
I would personaly do simple Swagger YAML and I would not integrate it<br>
to sources directly. Having it separate has another advantage like you<br>
can move that YAML here and there plus you can design endpoints and<br>
you can share it with other people before you even start to implement<br>
it.<br>
<br>
>From my point of view in work, this is really marginal issue for me<br>
right now. I just proposed the idea.<br>
<br>
Regards<br>
<div><div class="h5"><br>
On Tue, Apr 7, 2015 at 9:54 AM, Lukáš Fryč <<a href="mailto:lukas.fryc@gmail.com">lukas.fryc@gmail.com</a>> wrote:<br>
> I agree with Idel that DRY approach in Miredot's case seems more appealing.<br>
><br>
> They offer basic docs generation in Free version, but also Pro version for<br>
> open-source projects under conditions that Aerogear meets [1].<br>
><br>
> ~ Lukas<br>
><br>
> [1] <a href="http://www.miredot.com/price/" target="_blank">http://www.miredot.com/price/</a><br>
><br>
> ne 5. 4. 2015 v 20:00 odesílatel Idel Pivnitskiy <<a href="mailto:idel.pivnitskiy@gmail.com">idel.pivnitskiy@gmail.com</a>><br>
> napsal:<br>
><br>
>> For JAX-RS I prefer use MireDot as a REST API doc generator<br>
>> <a href="http://www.miredot.com/" target="_blank">http://www.miredot.com/</a><br>
>><br>
>> With MireDot you do not need to use additional annotations, like @Api:<br>
>><br>
>> @Path("/pet")<br>
>> @Api(value = "/pet", description = "Operations about pets")<br>
>><br>
>><br>
>> It will parse your JAX-RS annotation and pure javadoc:<br>
>><br>
>> /**<br>
>> * Operations about pets<br>
>> */<br>
>> @Path("/pet")<br>
>><br>
>> and generate beautiful and user friendly documentation, like this:<br>
>> <a href="http://www.miredot.com/exampledocs/" target="_blank">http://www.miredot.com/exampledocs/</a><br>
>> Swagger example: <a href="http://petstore.swagger.io/" target="_blank">http://petstore.swagger.io/</a><br>
>><br>
>> And MireDot is free for open source projects!<br>
>><br>
>> Think about this alternative for Swagger. I'm able to prepare Pull Request<br>
>> for UPS next week.<br>
>><br>
>><br>
>> 2015-04-04 9:43 GMT+03:00 Matthias Wessendorf <<a href="mailto:matzew@apache.org">matzew@apache.org</a>>:<br>
>>><br>
>>><br>
>>><br>
>>> On Fri, Apr 3, 2015 at 10:27 PM, Heiko W.Rupp <<a href="mailto:hrupp@redhat.com">hrupp@redhat.com</a>> wrote:<br>
>>>><br>
>>>> On 3 Apr 2015, at 18:53, Andrea Vibelli wrote:<br>
>>>><br>
>>>> > we are using it in Project Newcastle with annotations on the<br>
>>>> > endpoints, and<br>
>>>> > it's really handy.<br>
>>>><br>
>>>> All the JBoss ON 3.2+ and RHQ REST-docs are generated from JAX-RS +<br>
>>>> Swagger annotations.<br>
>>>> In Hawkular we are basically doing the same, but with a different<br>
>>>> annotation processor.<br>
>>><br>
>>><br>
>>> +1000<br>
>>><br>
>>> we are, atm, doing similar:<br>
>>> source<br>
>>><br>
>>> <a href="https://github.com/aerogear/aerogear-unifiedpush-server/blob/master/jaxrs/src/main/java/org/jboss/aerogear/unifiedpush/rest/sender/PushNotificationSenderEndpoint.java#L99-L102" target="_blank">https://github.com/aerogear/aerogear-unifiedpush-server/blob/master/jaxrs/src/main/java/org/jboss/aerogear/unifiedpush/rest/sender/PushNotificationSenderEndpoint.java#L99-L102</a><br>
>>> result:<br>
>>><br>
>>> <a href="https://aerogear.org/docs/specs/aerogear-unifiedpush-rest/sender/index.html#POST" target="_blank">https://aerogear.org/docs/specs/aerogear-unifiedpush-rest/sender/index.html#POST</a><br>
>>><br>
>>> but the jaxrs doclet does not work w/ JDK8 - something has to change here<br>
>>> ;-)<br>
>>> So, I am all for using Swagger annotations on the code to generate the<br>
>>> HTML docs :-)<br>
>>><br>
>>> Greetings,<br>
>>> Matthias<br>
>>><br>
>>>><br>
>>>><br>
>>>> I personally think the best is really to have the annotations in the<br>
>>>> source and not trying<br>
>>>> to update a separate .yml file, as the latter usually is much easier<br>
>>>> forgotten.<br>
>>>> _______________________________________________<br>
>>>> aerogear-dev mailing list<br>
>>>> <a href="mailto:aerogear-dev@lists.jboss.org">aerogear-dev@lists.jboss.org</a><br>
>>>> <a href="https://lists.jboss.org/mailman/listinfo/aerogear-dev" target="_blank">https://lists.jboss.org/mailman/listinfo/aerogear-dev</a><br>
>>><br>
>>><br>
>>><br>
>>><br>
>>> --<br>
>>> Matthias Wessendorf<br>
>>><br>
>>> blog: <a href="http://matthiaswessendorf.wordpress.com/" target="_blank">http://matthiaswessendorf.wordpress.com/</a><br>
>>> sessions: <a href="http://www.slideshare.net/mwessendorf" target="_blank">http://www.slideshare.net/mwessendorf</a><br>
>>> twitter: <a href="http://twitter.com/mwessendorf" target="_blank">http://twitter.com/mwessendorf</a><br>
>>><br>
>>> _______________________________________________<br>
>>> aerogear-dev mailing list<br>
>>> <a href="mailto:aerogear-dev@lists.jboss.org">aerogear-dev@lists.jboss.org</a><br>
>>> <a href="https://lists.jboss.org/mailman/listinfo/aerogear-dev" target="_blank">https://lists.jboss.org/mailman/listinfo/aerogear-dev</a><br>
>><br>
>><br>
>><br>
>><br>
>> --<br>
>> Best regards,<br>
>> Idel Pivnitskiy<br>
>> E-mail: <a href="mailto:Idel.Pivnitskiy@gmail.com">Idel.Pivnitskiy@gmail.com</a><br>
>> Twitter: @idelpivnitskiy<br>
>> GitHub: @idelpivnitskiy<br>
>> _______________________________________________<br>
>> aerogear-dev mailing list<br>
>> <a href="mailto:aerogear-dev@lists.jboss.org">aerogear-dev@lists.jboss.org</a><br>
>> <a href="https://lists.jboss.org/mailman/listinfo/aerogear-dev" target="_blank">https://lists.jboss.org/mailman/listinfo/aerogear-dev</a><br>
><br>
><br>
> _______________________________________________<br>
> aerogear-dev mailing list<br>
> <a href="mailto:aerogear-dev@lists.jboss.org">aerogear-dev@lists.jboss.org</a><br>
> <a href="https://lists.jboss.org/mailman/listinfo/aerogear-dev" target="_blank">https://lists.jboss.org/mailman/listinfo/aerogear-dev</a><br>
<br>
<br>
<br>
--<br>
</div></div><span class="">Stefan Miklosovic<br>
Red Hat Brno - JBoss Mobile Platform<br>
<br>
</span>e-mail: <a href="mailto:smikloso@redhat.com">smikloso@redhat.com</a><br>
irc: smikloso<br>
<div class="HOEnZb"><div class="h5"><br>
_______________________________________________<br>
aerogear-dev mailing list<br>
<a href="mailto:aerogear-dev@lists.jboss.org">aerogear-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/aerogear-dev" target="_blank">https://lists.jboss.org/mailman/listinfo/aerogear-dev</a></div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature">Matthias Wessendorf <br><br>blog: <a href="http://matthiaswessendorf.wordpress.com/" target="_blank">http://matthiaswessendorf.wordpress.com/</a><br>sessions: <a href="http://www.slideshare.net/mwessendorf" target="_blank">http://www.slideshare.net/mwessendorf</a><br>twitter: <a href="http://twitter.com/mwessendorf" target="_blank">http://twitter.com/mwessendorf</a></div>
</div>