Hi Yves,

thanks a lot!

Idel, below is the license key - I saw (looking at your Tika link) it needs to be included on the pom.xml file.

Cheers,
Matthias


---------- Forwarded message ----------
From: Yves Vandewoude <yves.vandewoude@miredot.com>
Date: Thu, Apr 9, 2015 at 10:07 AM
Subject: Re: License Key for AeroGear UnifiedPush Server (was: Re: [aerogear-dev] do we want swagger for REST endpoint documentation?)
To: Matthias Wessendorf <matzew@apache.org>


Hello Matthias,

The licence key for the  AeroGear UnifiedPush Server project is:

<licence>cHJvamVjdHxvcmcuamJvc3MuYWVyb2dlYXIudW5pZmllZHB1c2gudW5pZmllZHB1c2gtamF4cnN8MjAxNy0wNS0wMXx0cnVlfC0xI01Dd0NGQitaa0VVRVlsaU9LQjljR2h5TWNSWm1VMTREQWhRbUlHOXY3MExCR0FoT2FubklFSER2SWl1OVZnPT0=</licence>

It is valid for two years (until May 1st 2017) for org.jboss.aerogear.unifiedpush / unifiedpush-jaxrs 

After that, you are free to request a new licence key.

We continuously aim to improve our tool, so do not hesitate to contact us if you have any questions or remarks. Support questions are best sent to support@miredot.com, since they are dealt with by a team instead of just me :)

Kind regards,
Yves

Matthias Wessendorf schreef op 9/04/2015 om 9:46:
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




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