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@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@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@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

--

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

--

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