@ReturnType

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:

• Use fully qualified names
• Make no spelling errors

@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.