search

ryankennedy / swagger-jaxrs-doclet

Apache License 2.0
87 stars 136 forks source link

REST method return type overriding (solves not generating models for javax.ws.rs.core.Response) #71

Open code77 opened 10 years ago

code77 commented 10 years ago

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.