Documenting custom error codes from ASP.NET Web API [closed] - asp.net-web-api

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
Are there any best practices for documenting possible error codes returned from a Web API call? I'm referring to custom logic errors as opposed to standard HTTP return codes.
For example, consider an API method to allow a user to change their password. A possible error condition might be that the new password provided has already been used by that user previously (ie, password history requirement). You could use the following code to communicate that to the caller:
public HttpResponseMessage ChangePassword(string oldPassword, string newPassword)
{
try
{
passwordService.ChangePassword(oldPassword, newPassword)
return Request.CreateResponse(HttpStatusCode.OK);
}
catch (Exception ex)
{
switch(ex.Message)
{
case "PasswordHistoryFailed":
return Request.CreateResponse(HttpStatusCode.BadRequest, new CustomErrorClass("FailedHistoryRequirements"));
break;
...
}
}
}
In this example, I'm using a custom error class to wrap a custom error code of "FailedHistoryRequirements". I could have more error codes for this operation such as too many password changes in a 24 hour period or whatever.
I want to know if there's an accepted way to automatically document these custom error codes in the method's XML Code Comments so that it can be consumed by a documentation generator like Swashbuckle/Swagger or something similar.

Answer 1

If you use Swagger, you can use the SwaggerResponse attribute.
Check out this blog post:
https://mattfrear.com/2015/04/21/generating-swagger-example-responses-with-swashbuckle/

Answer 2

I do this by catching a specific exception type, rather than parsing the message.
Here I have MyDepartmentCentricBaseException as a custom exception. I may have 2-3 exceptions that derive from it. But by using a base-exception, I keep my exception catching cleaner.
try
{
/* do something */
}
catch (MyDepartmentCentricBaseException deptEx)
{
HttpResponseException hrex = this.GetDepartmentMissingHttpResponseException(deptEx.DepartmentSurrogateKey);
throw hrex;
}
catch (Exception ex)
{
/* log it somewhere !*/
throw new HttpResponseException(HttpStatusCode.InternalServerError);
}
private HttpResponseException GetDepartmentMissingHttpResponseException(int DepartmentSurrogateKey)
{
HttpResponseMessage resp = new HttpResponseMessage(HttpStatusCode.NotFound)
{
Content = new StringContent(string.Format("No Department with DepartmentSurrogateKey = {0}", DepartmentSurrogateKey)),
ReasonPhrase = "DepartmentSurrogateKey Not Found"
};
HttpResponseException returnEx = new HttpResponseException(resp);
return returnEx;
}
There are other ideas here:
https://learn.microsoft.com/en-us/aspnet/web-api/overview/error-handling/exception-handling
But I don't know of a way of auto-voodoo-it with documentation. :(