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

Question

我正在将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并将MyClassType2其显示在帮助页面上。

我看过的所有地方，到目前为止似乎还不支持。但是，我想知道是否有人能够通过扩展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()上面的方法在哪里实现，如下所示：如何使用反射获得正确的泛型类型的文本定义？

但是，这并不能为我提供这些类的注释，并且对嵌套类型没有帮助（例如，如果我的模型上具有复杂类型的属性，则不会显示该复杂类型的属性）。而且，如果没有它们的XML注释，这些类型就没有足够的用处。

同样，这仅适用于参数，而不适用于HttpResponseMessage主体中包含的返回类型。通过执行ResponseTypeAttribute如下所示，我能够使响应示例正常工作：返回类型为HttpResponseMessage的自动生成的帮助页面，但是同样，该页面没有提供带有XML注释的属性。我可以使用反射来获得类型，就像再次获得参数类型一样，但是我确实希望XML注释与类型一起使用，包括嵌套的复杂类型。

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

有没有人能够实现与我要为参数或返回类型（最好同时为两者）执行的操作类似的操作？或有什么想法可以指出正确的方向？

Answer 1

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

目前，我们也仅记录操作的输入类型，而不记录响应类型，因为通常用户希望了解输入类型的信息。但是我可以看到用户也可能需要响应类型的信息以供消费...我们将对此进行调查，并让您知道。