[aerogear-dev] do we want swagger for REST endpoint documentation?
Idel Pivnitskiy
idel.pivnitskiy at gmail.com
Tue Apr 7 07:42:18 EDT 2015
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 :)
2015-04-07 14:11 GMT+03:00 Matthias Wessendorf <matzew at apache.org>:
>
>
> 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
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20150407/ff1d2db6/attachment-0001.html
More information about the aerogear-dev
mailing list