
Miredot normally uses the return type of your Java method to determine how the output of a REST endpoint should be
documented. Some projects, however, strongly rely on the use of javax.ws.rs.core.Response
or similar types. In those
cases, Miredot can derive very little information from the return type and will by default visualize the result of the
interface as ???.
In order to provide adequate documentation for these cases, Miredot provides the @ReturnType
annotation, which overrides
the return type of the method. Whenever this annotation is present on a method, the actual return type
is ignored, and Miredot will document whatever type is described within the annotation. An example of the use of such
annotation is as follows:
@Path("/rest/car/")
public interface CarService {
/**
* @summary Retrieve the specified part of this car
* @param carId The id of the car whose part is to be retrieved
* @param partId The id of the part that is to be retrieved
* @returns the specified part of the car
*/
@GET
@Path("{carId}/carParts/{partId}")
@Produces("application/json")
@ReturnType(clazz = CarPart.class)
Response getPart(@PathParam("carId") Long carId, @PathParam("partId") Long partId);
}
When you want to specify a generic type as the return type you must use the value attribute of the annotation (that
accepts a String
). In this case it is important that you:
@Path("/rest/car/")
public interface CarService {
/**
* @summary Retrieve the parts of this car
* @param carId The id of the car whose parts are to be retrieved
* @returns the different parts of the car
*/
@GET
@Path("{carId}/carParts")
@Produces("application/json")
@ReturnType("java.util.List<com.company.package.car.parts.CarPart>")
Response getParts(@PathParam("carId") Long carId);
}
You can also use generic type parameters of the enclosing class in the type specification. For example, the following is supported:
public abstract Class AbstractCarInterface<T> {
@GET
@Path("{description}")
@Produces("application/json")
@ReturnType("com.company.package.Brand<T>")
Response getBrand(@PathParam("description") String description);
}
@Path("/fancycarbrand")
public Class FancyCarInterface extends AbstractCarInterface<FancyCarBrand> {
}
Note: you can also write @ReturnType("java.lang.Void")
to completely ignore the
declared return type. This can be useful if you declare javax.ws.rs.core.Response
as return type but in fact only
use it to set for example the HTTP code and don't provide a response body.