Question

I’m wondering how to write documentation comments for HttpResponseException exceptions thrown by ASP.NET Web API controllers? The thing is that, normally you throw a different kind of exception for each case and hence write a documentation comment for each exception type, e.g /// <exception cref="ResourceNotFound">Resource not found</exception>. However, with HttpResponseException, the StatusCode property of the exception is what identifies the error case.

How should I document each of the cases where HttpResponseException may be thrown, each identified by a status code, corresponding to how you otherwise write an /// <exception></exception> comment per exception type?

Answer 1

I’ve found a solution that lets me document error cases in Web API controller methods as one does for normal C# exceptions – map each HTTP status code you want to use for flagging errors to a subclass of HttpResponseException. This solves my particular problem, which was just down to describing error cases in the documentation comments of Web API controller methods.

Consider the following code as an example:

public class HttpNotFoundException : HttpResponseException
{
    public HttpNotFoundException(string reason)
        : base(new HttpResponseMessage { StatusCode = HttpStatusCode.NotFound, ReasonPhrase = reason })
    { }
}

public class HttpInternalServerError : HttpResponseException
{
    public HttpInternalServerError(string reason)
        : base(new HttpResponseMessage { StatusCode = HttpStatusCode.InternalServerError, ReasonPhrase = reason })
    { }
}

public class ResourceApiController : ApiController
{
    IRepository Repository { get; set; }

    /// <summary>
    /// Delete a resource.
    /// </summary>
    /// <param name="id">Resource ID.</param>
    /// <exception cref="HttpNotFoundException">Resource not found.</exception>
    /// <exception cref="HttpInternalServerError">An internal error was detected, for instance in database service.</exception>
    public void DeleteResourceById(string id)
    {
        try
        {
            Repository.Delete(id);
        }
        catch (WebResourceNotFoundError)
        {
            throw new HttpNotFoundException(string.Format("Build '{0}' not found", id));
        }
        catch (DatabaseServiceException)
        {
            throw new HttpInternalServerError("Database service operation failed");
        }
    }
}