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

我希望MyClassType1和MyClassType2上的XML评论显示在上述帖子操作的帮助页面上。

我看过的每个地方，到目前为止看来还没有支持。但是，我想知道是否有人能够通过扩展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()方法实现如下所示：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注释的属性）与服务调用分开记录是可以接受的，并且让服务调用只显示它们返回的类型的名称（至少是用户可以找到该类型的文档。）

有没有人能够实现类似于我试图对参数或返回类型执行的操作，最好是两者？还是有任何想法指出我正确的方向？

Answer 1

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

目前我们只记录操作的输入类型，而不是通常用户想要了解输入类型信息的响应类型。但是我可以看到用户可能也想要消费的响应类型的信息......我们会调查这个并告诉你。

Answer 2

您可以在文档评论 Here is a Reference中进行修改以允许html。

在允许HTML之后，您可以将包含属性信息的表放在XML文档参数标记描述的位置。您还可以查看帮助页HTML源以获取用于帮助页表的类属性名称，以便您的表将使用与所有其他表相同的CSS。

这是一个黑客，但它完美无缺。

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

2 个答案: