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

Tue Apr 7 05:57:06 EDT 2015

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