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

Matthias Wessendorf matzew at apache.org
Tue Apr 7 07:11:19 EDT 2015


On Tue, Apr 7, 2015 at 12:56 PM, Idel Pivnitskiy <idel.pivnitskiy at gmail.com>
wrote:

> Yes, Swagger can generate doc on the fly, but Swagger use its own
> annotations instead of parse JAX-RS annotations and javadoc, like MireDot.
>

Ok, I think I have not a huge concern against custom annotations,
especially due to the wide adoption of Swagger.
I guess it's just a very tiny JAR, that contains the annotations, right?

(+ the build time tool dependency for processing)


> What about licence: Apache Tika, for example, uses pro version of MireDot
>
>
> https://github.com/apache/tika/blob/5fbc56cca94b9da0a914e82dd466abb139f9e3f4/tika-server/pom.xml#L248-L266
>

Thanks for the example, that's helpful


>
>
> 2015-04-07 13:48 GMT+03:00 Matthias Wessendorf <matzew at apache.org>:
>
>> 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
>>
>> _______________________________________________
>> 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/091bab39/attachment.html 


More information about the aerogear-dev mailing list