Support documentation of warning codes

Rob Lyon added a comment - 20/Mar/12 3:04 PM Example: @PUT @StatusCodes( { @ResponseCode(code = 204, condition = "The update was successful.") @ResponseCode(code = 409, condition = "If the update created a conflict.") } ) @Warnings( { @ResponseCode(code = 301, condition = "The update would have created two cars with the same VIN.") @ResponseCode(code = 302, condition = "The update would have created two cars with the same license plate number.") } ) void put(Car car, @PathParam("id") String id) { /** put */ }

Rob Lyon added a comment - 20/Mar/12 5:08 PM What do you think about renaming the status sub-code on WebServiceException to warning?

C Roskelley added a comment - 22/Mar/12 8:04 AM Another proposal would be to inline the warning code and its documentation description with the HTTP Status code. @PUT @StatusCodes({ @ResponseCode(code = 204, condition = "The update was successful." ) @ResponseCode(code = 409, condition = "If the update created a conflict." ) @ResponseCode(code = 400, condition = "Bad or malformed request." , warningCode = 197, warningCondition= "The update would have created two cars with the same VIN." ) @ResponseCode(code = 400, condition = "Bad or malformed request." , warningCode = 198, warningCondition= "The update would have created two cars with the same license plate number." ) }) void put(Car car, @PathParam( "id" ) String id) { /** put */ } In this way it can clearly be seen when the warning codes would be applicable. Not all HTTP Status codes will generate warnings. And some HTTP Status codes will have one or more warnings.

Ryan Heaton added a comment - 25/Jul/12 5:04 PM Fixed at 5259ec4. I decided to use a separate annotation, @org.codehaus.enunciate.jaxrs.Warnings because even though additional context would be nice, I'm afraid it might require too much redundancy. Since a warning might apply to multiple status codes, you would not only have to repeat the condition for each status code, but then the same warning would have to be repeated across different status codes that apply the same warning.

Ryan Heaton added a comment - 15/Aug/12 10:11 AM Closed with the release of 1.26.