WebAPI幫助頁面 - 返回或參數模型/類屬性的文檔

我正在使用Web API幫助頁面和Web API 2（5.0） - 都是最新的Nuget包。我希望幫助文檔能夠在HttpResponseMessage的主體中顯示屬性對參數或返回的類的註釋。WebAPI幫助頁面 - 返回或參數模型/類屬性的文檔

例如，我有一個控制器的方法是這樣的：

public HttpResponseMessage Post([FromBody] MyClassType1 myClass) 
{ 
    // Business logic removed for clarity 
    return Request.CreateResponse(HttpStatusCode.OK, new MyClassType2()); 
}

我想，我對MyClassType1和MyClassType2要顯示幫助頁面上的上述動作後的XML註釋。

到處都是我看過的，到目前爲止似乎還沒有被支持。但是，我想知道是否有人能夠通過擴展ApiExplorer，添加到XmlDocumentationProvider等得到這個工作嗎？

我知道註釋和屬性包含在生成的XML文件中，所以我可以嘗試手動解析（所有參數和返回類型都在MyAssemblyName.Models命名空間中，所以我的想法是我可以找但是，我知道內置的web API幫助頁面有一些緩存功能，所以我更願意將其與現有功能結合使用（只需將其添加到該功能中）

我已成功地顯示參數類型（下一層只）通過更新Parameters.cshtml模板這樣：

@using System.Reflection 
@using System.Threading 
@using System.Web.Http.Description 
@using Regency.API.Services.Areas.HelpPage 
@model System.Collections.ObjectModel.Collection<ApiParameterDescription> 

<table class="help-page-table"> 
    <thead> 
     <tr><th>Name</th><th>Properties</th><th>Description</th><th>Additional information</th></tr> 
    </thead> 
    <tbody> 
     @foreach (ApiParameterDescription parameter in Model) 
     { 
      string parameterDocumentation = parameter.Documentation ?? "No documentation available."; 
      Type parameterType = parameter.ParameterDescriptor.ParameterType; 

      // Don't show CancellationToken because it's a special parameter 
      if (!typeof (CancellationToken).IsAssignableFrom(parameter.ParameterDescriptor.ParameterType)) 
      { 
       <tr> 
        <td class="parameter-name"><b>@parameter.Name</b></td> 
        <td class="parameter-properties"> 
         @foreach (PropertyInfo property in parameterType.GetProperties()) 
         { 
          <text>@property.Name : @property.PropertyType.GetFriendlyTypeName()</text> 
          <br/> 
         } 
        </td> 
        <td class="parameter-documentation"><pre>@parameterDocumentation</pre></td> 
        <td class="parameter-source"> 
         @switch(parameter.Source) 
         { 
          case ApiParameterSource.FromBody: 
           <p>Define this parameter in the request <b>body</b>.</p> 
           break; 
          case ApiParameterSource.FromUri: 
           <p>Define this parameter in the request <b>URI</b>.</p> 
           if (parameter.ParameterDescriptor.IsOptional) 
           { 
            <p>This parameter is <b>optional</b>.</p> 
           } 
           break; 
          default: 
           <p>None.</p> 
           break; 
         } 
        </td> 
       </tr> 
      } 
     } 
    </tbody> 
</table>

其中GetFriendlyTypeName()上述方法實現如下所示：How can I get the correct text definition of a generic type using reflection?

然而，這並不讓我從這些類的意見，並沒有與嵌套類型幫助（例如如果我的模型具有複雜類型的屬性，它不會顯示該複雜類型屬性的屬性）。無論如何，如果沒有XML註釋，這些類型就沒有用處了。

此外，這僅適用於參數，但不適用於返回HttpResponseMessage正文中包含的類型。我可以通過執行ResponseTypeAttribute來獲取響應示例，如下所示：Auto generated help pages with return type HttpResponseMessage但是，這又不能給我帶有XML註釋的屬性。我可以使用反射來獲取類型，類似於我再次獲取參數類型的方式，但我真的很想將XML註釋與類型一起使用，並且包括嵌套的複雜類型。

我也會發現它可以接受與服務調用分開記錄模型/類文檔（類型和XML註釋的屬性），並使服務調用只顯示它們返回的類型的名稱（然後至少用戶可以找到該類型的文檔）。

有沒有人能夠實現類似於我想要做的任何參數或返回類型，最好是兩者？或者有什麼想法可以讓我指出正確的方向？

來源

2013-10-28 mayabelle

記錄複雜類型的單個屬性的功能目前正在開發中，並且可用於下一版本。這就是說你目前可以從Nightly builds獲得HelpPage包並試用它。您應該可以將此軟件包升級到現有的5.0 web api項目。

目前我們只記錄動作的輸入類型，而不是響應類型，因爲通常用戶會想知道輸入類型的信息。但是我可以看到，用戶可能也需要響應類型的信息以供消費......我們會研究這一點，並讓您知道。

來源

2013-10-28 23:43:25

謝謝基蘭。下一個發佈計劃何時計劃？我認爲記錄響應類型將是一個包含API的重要方面，並且希望這個功能也能夠將其納入下一個版本。是否有博客或論壇帖子關注新增功能？ – mayabelle

我無權透露發佈日期： - ）...但我可以肯定地說，這個功能將在下一個版本中提供。我們目前正在對此功能做一些最後的修改，可能會在此發佈博客... –

可以理解。 :)博客會在http://blogs.msdn.com？ – mayabelle

您可以進行修改以允許在文檔註釋 Here is a Reference中使用html。

在允許使用HTML之後，您可以在XML文檔參數標記描述所在的位置放置一個具有屬性信息的表格。您還可以查看幫助頁面HTML源代碼，以獲取用於幫助頁面表的類屬性名稱，以便您的表格將使用與所有其他表格相同的CSS。

這是一個黑客，但它完美的作品。

來源

2015-02-19 16:07:38

WebAPI幫助頁面 - 返回或參數模型/類屬性的文檔

回答

相關問題