ASP.NET Web APIからのカスタムエラーコードの文書化

Question

Web API呼び出しから返される可能性のあるエラーコードを文書化するためのベストプラクティスはありますか？私は、標準のHTTPリターンコードとは対照的に、カスタムロジックエラーを指しています。

たとえば、ユーザーがパスワードを変更できるようにするAPIメソッドを考えます。考えられるエラー条件は、提供された新しいパスワードが以前にそのユーザーによって既に使用されていること（つまり、パスワード履歴要件）である可能性があります。あなたは、呼び出し元にそれを通信するために、次のコードを使用することができます。

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; 
       ... 
      } 


     } 
    } 

この例では、私は「FailedHistoryRequirements」のカスタムエラーコードをラップするカスタム・エラー・クラスを使用しています。私はこの操作のために、24時間の間にパスワードの変更が多すぎるなどのエラーコードを追加することができます。

Swashbuckle/Swaggerのようなドキュメントジェネレーターなどで消費されるように、メソッドのXMLコードコメントにこれらのカスタムエラーコードを自動的に記述する方法があるかどうかを知りたいと思います。

Answer 1

このブログの記事をチェックアウト：。。

https://mattfrear.com/2015/04/21/generating-swagger-example-responses-with-swashbuckle/

Answer 2

私は、メッセージを解析するのではなく、特定の例外タイプをキャッチすることでこれを行います。

ここで私はカスタム例外としてMyDepartmentCentricBaseExceptionを持っています。私はそれから派生する2-3の例外を持っているかもしれません。しかし、基底例外を使用することによって、私は例外をよりきれいにすることができます。そこ

 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; 
    } 

他のアイデアはここにある：

https://docs.microsoft.com/en-us/aspnet/web-api/overview/error-handling/exception-handling

しかし、私は、ドキュメントと自動ブードゥー教、それの方法を知っていません。 :(あなたが闊歩を使用する場合は、あなたがSwaggerResponse属性を使用することができます