ryankennedy/swagger-jaxrs-doclet — pull request #71 by code77 (2014-06-17 18:57:32+00:00)
Title: REST method return type overriding (solves not generating models for javax.ws.rs.core.Response)

Problem
------------------
This change addresses a problem where there's no model information generated if the return type of a REST method is wrapped inside javax.ws.rs.core.Response object (often the case).
http://docs.oracle.com/javaee/7/api/javax/ws/rs/core/Response.html

Current situation
------------------
Currently model generation from javax.ws.rs.core.Response is not supported at all because packages starting with "javax." are excluded from model documentation by this tool. Even if it wasn't excluded, it's impossible to find out which object is wrapped by javax.ws.rs.core.Response since its type is not known at compilation time - it's kept as Object

http://docs.oracle.com/javaee/7/api/javax/ws/rs/core/Response.html#ok(java.lang.Object)

Proposed solution
------------------
An additional, optional doclet parameter, that points to a conf file (standard java properties file) with mapping:
qualified method name -> java type that should be used for model generation

e.g.
fixtures.sample.Service.getSubResourceWrappedInResponse(java.lang.String,java.lang.String)=fixtures.sample.SubResource

Other solutions
------------------
Instead of using a mapping in a separate configuration file, it is be possible to use an annotation (an approach used by enunciate project: @org.codehaus.enunciate.jaxrs.TypeHint)
In this approach however, non-standard annotations have to be added to the code.