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

[Idel Pivnitskiy]

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