【发布时间】：2013-10-28 23:29:16
【问题描述】：
我正在使用带有 Web API 2 (5.0) 的 Web API 帮助页面 - 都是最新的 Nuget 包。我希望帮助文档显示作为参数或在 HttpResponseMessage 正文中返回的类的属性的 cmets。
例如，我有一个这样的控制器方法：
public HttpResponseMessage Post([FromBody] MyClassType1 myClass)
{
// Business logic removed for clarity
return Request.CreateResponse(HttpStatusCode.OK, new MyClassType2());
}
我希望我在 MyClassType1 和 MyClassType2 上拥有的 XML cmets 显示在上述发布操作的帮助页面上。
我看过的所有地方，到目前为止似乎还不支持。但是，我想知道是否有人能够通过扩展 ApiExplorer、添加到 XmlDocumentationProvider 等来使其工作？
我知道 cmets 和属性包含在生成的 XML 文件中，所以我可以尝试手动解析它（所有参数和返回类型都在 MyAssemblyName.Models 命名空间中，所以我的想法是我可以看看对于具有以该命名空间开头的成员名称的 XML 节点。但是，我知道内置的 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?
但是，这不会让我从这些类中获取 cmets，并且它对嵌套类型没有帮助（例如，如果我的模型上有一个复杂类型的属性，它不会显示该复杂类型的属性财产）。无论如何，如果没有它们的 XML cmets，这些类型就不够用了。
此外，这仅适用于参数，但不适用于 HttpResponseMessage 正文中包含的返回类型。我可以通过实现ResponseTypeAttribute 来使响应样本正常工作，如下所示：Auto generated help pages with return type HttpResponseMessage 但同样没有给我 XML cmets 的属性。我可以使用反射来获取类型，类似于我再次获取参数类型的方式，但我真的希望 XML cmets 与类型一起，包括嵌套的复杂类型。
我还发现将模型/类文档（具有类型和 XML cmets 的属性）与服务调用分开记录是可以接受的，并且让服务调用只显示它们返回的类型的名称（然后至少用户可以找到该类型的文档）。
有没有人能够实现类似于我试图为参数或返回类型做的事情，最好是两者？或者有什么想法可以为我指明正确的方向？
【问题讨论】：
标签： c# asp.net-mvc asp.net-web-api asp.net-mvc-apiexplorer asp.net-web-api-helppages