ryankennedy/swagger-jaxrs-doclet — pull request #60 by t-beckmann (2013-12-19 09:15:10+00:00)
Title: Fixpack: passing of -typesToTreatAsOpaque command line option, support for JResponse<T>, Map value type extraction, skipping of static fields and support for XmlAccessorType property or field.

Hi,

I'm having a larger code base and decided to use your nice doclet for Swagger metadata extraction. The JAX-RS classes are more or less complex. So I had to do several enhancements to make the doclet compatible with what I got here. I'm not a GIT user, so please excuse that I could not separate the features added in separate commits. However, you may find reading the diff not too complicated as the code is quite simple.

Here is a summary of the changes:

1. the option -typesToTreatAsOpaque could not be passed via javadoc command line. This is fixed in ServiceDoclet.java

2. for Jersey's JResponse generic response data type one just needs to extract the generic type and operate on that to generate the models instead of generating for JResponse. This was fixed in ApiMethodParser.java.

3. static fields and methods are skipped using the if's (if (field.isStatic() || field.name().charAt(0) == '_')) introduced in ApiModelParser.findReferencedTypes(). Also any names starting with _ are skipped. These fields and methods are introduced by EclipseLink static code weaving when model types are woven for lazy loading...

4. Also in ApiModelParser.findReferencedTypes() the XmlAccessorType annotation is now read to skip either methods or fields altogether if the accessor type is set to PROPERTY or FIELD only. However, the other values NONE and PUBLIC...ONLY are not respected, the code behaves as before when encountered.

5. Finally java.util.Maps are now supported properly by the change in ApiModelParser.parseParameterisedTypeOf(). For JSON compatibility the key type must be String in this case and for Swagger only the value type (2nd generic argument) is relevant.

Notice, I like your doclet much much better than the runtime introspection approach as your way does not need to repeat all the documentation. One thing I'm suffering from still however is Swagger running in an endless loop when the model contains back references... but that's not an issue of the doclet but of Swagger itself...

Best regards,
Thomas.