WebAPI 帮助页面 - 返回或参数模型/类属性的文档

我正在使用 Web API 帮助页面和 Web API 2 (5.0) - 都是最新的 Nuget 包。我希望帮助文档显示作为参数或在 HttpResponseMessage 正文中返回的类的属性的注释。

例如，我有一个像这样的控制器方法：

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

我想要我的 XML 注释MyClassType1 and MyClassType2将显示在上述帖子操作的帮助页面上。

我看过的所有地方，到目前为止似乎还不支持这一点。但是，我想知道是否有人能够通过扩展 ApiExplorer、添加 XmlDocumentationProvider 等来使其工作？

我知道注释和属性包含在生成的 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()上述方法的实现如下所示：如何使用反射获得泛型类型的正确文本定义？ https://stackoverflow.com/questions/401681/how-can-i-get-the-correct-text-definition-of-a-generic-type-using-reflection/401824#401824

但是，这并没有让我获得这些类的注释，并且对嵌套类型没有帮助（例如，如果我的模型有一个复杂类型属性，它就不会显示该复杂类型属性的属性）。无论如何，如果没有 XML 注释，这些类型就不够有用。

此外，这仅适用于参数，但不适用于 HttpResponseMessage 正文中包含的返回类型。我能够通过实施一个响应样本来工作ResponseTypeAttribute如图所示：自动生成返回类型为 HttpResponseMessage 的帮助页面 https://stackoverflow.com/questions/17821088/auto-generated-help-pages-with-return-type-httpresponsemessage/17822786#17822786但同样，这并没有给我带有 XML 注释的属性。我可以使用反射来获取类型，类似于再次获取参数类型的方式，但我确实希望将 XML 注释与类型一起使用，并包括嵌套的复杂类型。

我还发现将模型/类文档（带有类型和 XML 注释的属性）与服务调用分开记录是可以接受的，并且让服务调用只显示它们返回的类型的名称（然后至少用户可以找到该类型的文档）。

有没有人能够实现与我尝试对参数或返回类型（最好是两者）执行的操作类似的操作？或者有什么想法可以指引我正确的方向吗？

记录复杂类型的各个属性的功能目前正在开发中，并将在下一个版本中提供。也就是说，您当前可以从 Nightly 版本获取 HelpPage 包并尝试一下。您应该能够将此包升级到现有的 5.0 Web api 项目。

此外，目前我们仅记录操作的输入类型，而不记录响应类型，因为用户通常希望了解输入类型的信息。但我可以看到用户可能也希望使用响应类型的信息......我们将调查这一点并让您知道。