Support for javadoc response tag hint

[rmpestano]

In some situations it is not possible/hard to infer Response via byte code analysis, for example in exception mappers and RequestFilters.

In this situations we could leverage javadoc tags, for example:

/**
 *  @response 401 Not authorized (class level tag applies to all resource methods)
 *  @response 403 Not authenticated
 */
@Path("/cars")
@Produces("application/json;charset=utf-8")
public class CarEndpoint {

    @Inject
    CarService carService;

 /**
     * Deletes a car based on its ID
     *
     * @response 400 business logic exception
     * @response 404 This response will be ignored because it is already added via byte code analysis
     * @param user name of the user to log in
     * @param id car ID
     */
    @DELETE
    @Path("/{id:[0-9][0-9]*}")
    @RestSecured //activates a container request filter (a.k.a interceptor) which can return a FORBIDDEN or UNAUTHORIZED  response  
    public Response deleteById(@HeaderParam("user") String user, @PathParam("id") Integer id) {
        Car entity = carService.findById(id);
        if (entity == null) {
            return Response.status(Status.NOT_FOUND).build();
        }
        carService.remove(entity); //here a ExceptionMapper can return a BAD_REQUEST response
        return Response.noContent().build();
    }

This will produce the following swagger.json:

 "delete":{
                "description":"Deletes a car based on its ID",
                "consumes":[
                ],
                "produces":[
                    "application/json;charset=utf-8"
                ],
                "parameters":[
                    {
                        "type":"integer",
                        "name":"id",
                        "in":"path",
                        "required":true,
                        "description":"car ID"
                    },
                    {
                        "type":"string",
                        "name":"user",
                        "in":"header",
                        "required":true,
                        "description":"name of the user to log in"
                    }
                ],
                "responses":{
                    "204":{
                        "description":"No Content",
                        "headers":{
                        }
                    },
                    "400":{
                        "description":"business logic exception",
                        "headers":{
                        }
                    },
                    "401":{
                        "description":"Not authorized",
                        "headers":{
                        }
                    },
                    "403":{
                        "description":"Not authenticated",
                        "headers":{
                        }
                    },
                    "404":{
                        "description":"Not Found",
                        "headers":{
                        }
                    }
                },

[sdaschner]

Merged and closed in 29c0669