Hi Miredot team,

for the AeroGear UnifiedPush Server ([1], [2]), we would like to start using miredot for our jaxrs endpoints ([3]). The Maven groupId is "org.jboss.aerogear.unifiedpush" and the artifactId is "unifiedpush-jaxrs".

Currently we are using jaxrs-doclet ([4]), but we are not happy with that.

The Server is an OpenSource project with regular releases, and it is licensed under the Apache 2.0 license.

For this project we would like to request an opensource license.

Thanks,
Matthias

[1] https://aerogear.org/push/#unifiedpush
[2] https://aerogear.org/docs/unifiedpush/ups_userguide/index/
[3] https://github.com/aerogear/aerogear-unifiedpush-server/tree/master/jaxrs
[4] https://aerogear.org/docs/specs/aerogear-unifiedpush-rest/overview-index.html



On Tue, Apr 7, 2015 at 1:57 PM, Idel Pivnitskiy <idel.pivnitskiy@gmail.com> wrote:
Ok, so I will wait a license key from you.

2015-04-07 14:55 GMT+03:00 Matthias Wessendorf <matzew@apache.org>:


On Tue, Apr 7, 2015 at 1:42 PM, Idel Pivnitskiy <idel.pivnitskiy@gmail.com> wrote:
IMO, custom annotations force you to duplicate code and documentation. Take a look at a more detailed example:
  @POST
  @Path("/{petId}")
  @Consumes({MediaType.APPLICATION_FORM_URLENCODED})
  @ApiOperation(value = "Updates a pet in the store with form data",
    consumes = MediaType.APPLICATION_FORM_URLENCODED)
  @ApiResponses(value = {
    @ApiResponse(code = 405, message = "Invalid input")})
  public Response  updatePetWithForm (
   @ApiParam(value = "ID of pet that needs to be updated", required = true)@PathParam("petId") String petId,
   @ApiParam(value = "Updated name of the pet", required = false)@FormParam("name") String name,
   @ApiParam(value = "Updated status of the pet", required = false)@FormParam("status") String status) {
    System.out.println(name);
    System.out.println(status);
    return Response.ok().entity(new com.wordnik.swagger.sample.model.ApiResponse(200, "SUCCESS")).build();
  }

It is much more simple with MireDot (also because javadoc could be generated automatically by IDE):
  /**
  * Updates a pet in the store with form data.
  *
  * @param petId ID of pet that needs to be updated
  * @param name Updated name of the pet
  * @param status Updated status of the pet
  */
  @POST
  @Path("/{petId}")
  @Consumes({MediaType.APPLICATION_FORM_URLENCODED})
  public Response  updatePetWithForm (@PathParam("petId") String petId,
                                      @FormParam("name") String name,
                                      @FormParam("status") String status) {
    System.out.println(name);
    System.out.println(status);
    return Response.ok().entity(new com.wordnik.swagger.sample.model.ApiResponse(200, "SUCCESS")).build();
  }
Really, I don't know why Swagger is so popular :)

That's quite a difference, and less verbose and less of duplication (DRY). So I'd say, let's try Miredot :-) 

Thanks for the valuable info, Idel!

-Matthias
 

2015-04-07 14:11 GMT+03:00 Matthias Wessendorf <matzew@apache.org>:


On Tue, Apr 7, 2015 at 12:56 PM, Idel Pivnitskiy <idel.pivnitskiy@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


Thanks for the example, that's helpful
 


2015-04-07 13:48 GMT+03:00 Matthias Wessendorf <matzew@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@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


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


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

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
result:

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



--

_______________________________________________
aerogear-dev mailing list
aerogear-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev



--
Best regards,
Idel Pivnitskiy
_______________________________________________
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

_______________________________________________
aerogear-dev mailing list
aerogear-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev



--
Best regards,
Idel Pivnitskiy

_______________________________________________
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



_______________________________________________
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



_______________________________________________
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



--
Best regards,
Idel Pivnitskiy

_______________________________________________
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